How API Firewall validates API traffic

API Firewall performs the following validations on the incoming requests to and outgoing responses from the protected API.

Host validation

API Firewall only accepts requests where the value of the host header matches the value of SERVER_NAME defined in API Firewall variables. Requests with a bad host are rejected and the API callers receive this error:

{
 "status": 404,
 "title": "host mapping",
 "detail": "Not Found",
 "instance": "https://52.214.xx.xx/api/user/info",
 "uuid": "74e8181a-xxxx-11ea-834c-8d49f5ed9ad7"
}

Path and verb validation

API Firewall only accepts paths and their corresponding verbs (methods) that match the OpenAPI definition of the API.

For example, if the OpenAPI definition specifies the following operation:

"paths": {
 "/category": {
 "get": {

In this case, API Firewall would reject API calls that use any other verbs than GET, or a different path name than /category.

Path and verb validation also validates that path parameters are present and their format, for example:

{
    "name": "accountId",
    "in": "path",
    "description": "Persistent unique identifier associated with an account",
    "required": true,
    "type": "string",
    "maxLength": 25,
    "minLength": 10,
    "pattern": "^[a-z0-9]+$",
}

A typical response to a rejected request looks like this:

{
 "status": 405,
 "title": "operation mapping",
 "detail": "Method Not Allowed",
 "instance": "https://42c-fw-lb-xxx/api/user/info",
 "uuid": "f491e67c-xxxx-11ea-9cd2-97313494c108"
}

Headers validation

API Firewall validates all headers against the headers declared in the OpenAPI definition. For example, the API definition might have the following definition for a header:

{
 "in": "header",
 "name": "X-IBM-Client-Id",
 "type": "string",
 "pattern": "[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[afA-F0-9]{12}",
 "maxLength": 36,
 "minLength": 36,
 "required": true
}

In this case, API Firewall would validate incoming requests for headers as follows:

1. A header named X-IBM-Client-Id is present.
2. The header is not shorter than minLength.
3. The header is not longer than maxLength.
4. The header matches pattern.

In addition to these, API Firewall also validates the value of Content-Type:

• OpenAPI Specification (OAS)v2: The value is checked against the property consumes defined for the operation in the API definition.
• OASv3: The value is checked against the list of MIME types defined in the property content of the request body for the operation in the API definition.

Headers that are defined in the API definition as a part of a security scheme must be present if the API operation in question uses that particular security scheme. For OAuth authentication, the Authorization header that uses a bearer token is required.

Query parameter validation

API Firewall validates all query parameters against their description in the API definition. For example:

{
 "name": "transactionFromDate",
 "in": "query",
 "description": "Starting range for transaction date",
 "required": true,
 "type": "string",
 "maxLength": 10,
 "minLength": 8,
 "pattern": "^\d{1,2}-\d{1,2}-\d{4}$"
}

Request body validation

API Firewall validates the request body against the schema you have specified for it in the OpenAPI definition of your API.

For example, an API might include the following definition for a request body:

"requestBody": {
    "description": "Correspondence to generate and send",
    "content": {
        "application/json": {
            "schema": {
                "$ref": "#/components/schemas/Case"
            }
        }
    }
},

Based on this definition, API Firewall checks the following:

• The request must include a body.
• Content-Type must be set to application/json.
• Body must match the referenced schema called Case.

To continue the example, let's assume that the referenced schema Case looks like this:

"Case": {
    "additionalProperties": false,
    "type": "object",
    "required": [ "caseId" ],
    "properties": {
        "caseId": {
            "type": "string",
            "pattern": "^[A-Z0-9]+$",
            "minLength": 10,
            "maxLength": 25
        },
        "status": {
            "type": "string",
            "enum": ["PENDING", "APPROVED", " REJECTED"]
        },
        "statusCode": {
            "type": "integer",
            "minimum": 400,
            "maximum": 429
        }
    }
}

Based on this, API Firewall proceeds to validate the following:

• The request body is an object.
• The required property caseId is present in the request body.
• All properties of the request body match the format and constraints that the API expects.
• There are no additional properties in the request body.

In case the request body definition includes arrays, API Firewall also enforces the constraints for the property maxItems.

API response validation

Like request body validations, API Firewall systemically validates all responses from the protected API against their respective schemas in the OpenAPI definition of the API. For example, the API definition might have the following definition for a response:

"404ResourceNotFoundError": {
    "description": "Resource Not Found Error",
    "content": {
        "application/json": {
            "schema": {
                "$ref": "#/components/schemas/Error"
            }
        }
    }
}

Based on this, API Firewall first validates that the response body is application/json. Then, API Firewall proceeds to validate that all properties of the response body match what has been defined in the referenced schema #/components/schemas/Error just like it does for request bodies.

API Firewall validates that all HTTP status codes (200, 401, 403, 500, and so forth) in API responses have a response defined for them in the API definition. Any responses with unknown (undefined) response codes are blocked. In this case, API Firewall generates the following default response:

{
    "status": 500,
    "title": "response validation",
    "detail": "Internal Server Error",
    "instance": "https://pru.42crunch-demos.com/api/admin/all_users",
    "uuid": "09db63e6-8bcc-11ea-a555-b3f607bf1c5b"
}

API Security Audit helps you spot any potentially missing responses in your API definition by flagging them in the audit.