Automatic contract enforcement

The automatic contract enforcement is the protection that you get for your API out-of-the-box when you deploy API Firewall. You do not need to add any security extensions to your OpenAPI definition to apply the automatic contract enforcement.

Description

API Firewall automatically enforces the API contract spelled out in your API definition. It filters out unwanted requests, only letting through the requests that should be allowed based on the OpenAPI definition of the API it protects. API Firewall also blocks any responses from the API that have not been declared or that do not match the API definition.

API Protection creates an allowlist of the valid operations and input data based on the API contract, and API Firewall enforces this configuration to all transactions, incoming requests as well as outgoing responses. Transactions containing things not described in the API definition are automatically blocked:

• Messages where the input or output data does not conform to the JSON schema
• Undocumented methods (POST, PUT, PATCH...)
• Undocumented error codes
• Undocumented schemas
• Undocumented query or path parameters

For more details on the validation that API Firewall performs, see How API Firewall validates API traffic.

Direction

This protection applies only to both incoming requests and outgoing responses.

Directional allowlist protections

Extensions for applying the protections:

• x-42c-deactivate-allowlist
• x-42c-request-allowlist_0.1
• x-42c-response-allowlist_0.1

Deactivating automatic contract enforcement should always be done on a case-by-case basis after a careful consideration. Deactivating it in the wrong place could have serious consequences to the security of your API.

You can add the extension x-42c-deactivate-allowlist directly to your OpenAPI definition, on any level to control when API Firewall applies allowlisting and when it does not: locally to specific paths, operations, responses, or HTTP status codes, or globally to all incoming requests or outgoing responses. You can also override the deactivation on another level: lower levels override higher levels. For more details, see Local and global protections.

You might want to switch off the allowlist for all outgoing responses, but keep it on for all incoming requests, or the other way round. In this case you can combine x-42c-deactivate-allowlist with the directional allowlist protections x-42c-request-allowlist_0.1 and x-42c-response-allowlist_0.1: first you deactivate the automatic allowlist for the whole API, then you add the directional allowlist that you want like any other additional protections (see Protections and security extensions).

For more details, see Deactivate automatic contract enforcement in API Firewall.

Parameters

Deactivating the automatic allowlist or the directional allowlist protections do not take any parameters.

Example

The following example shows how the automatic allowlist has been deactivates on an API operation, but kept active for a particular response:

# ...
paths:
    /apis:
        get:
            x-42c-deactivate-allowlist: true     # scope 'Operation'
            parameters:
                # ...
            responses:
                200:
                    x-42c-deactivate-allowlist: false   # scope 'Status'

Here, deactivating the automatic allowlist has been combined with activating directional allowlist for all incoming requests as well as for a particular API response:

# ...
description: Pixi Photo Sharing API
version: 1.0.0
# ...
x-42c-deactivate-allowlist: true
# ...
x-42c-request-strategies:
    - x-42c-strategy:
        protections:
            - x-42c-request-allowlist_0.1: {}
# ...
responses:
    200: 
        # ...            
        x-42c-local-strategy: 
            x-42c-strategy:
                protections:
                    - x-42c-response-allowlist_0.1: {}