x-42c extensions for API Protection and API Firewall

Extensions can have different scope depending on which level in your OpenAPI definition you add them:

• Global level: The extension applies to the whole API: all paths, operations, and responses.
• Path level: The extension applies to a specific path, including all operations and responses defined in it.
• Operation level: The extension is applied to a specific operation and its responses.
• Response level: The extension is applied to all responses defined for an operation.
• Status level: The extension is applied to a specific HTTP status code or the default response.

# ...
paths:
    /apis:
        x-42c-local-strategy:
            x-42c-strategy:
                protections:
                    - x-42c-request-limiter_0.1:                # path level
                        # ...
        get:
            x-42c-local-strategy:
                x-42c-strategy:
                    protections:
                        - x-42c-request-limiter_0.1:            # operation level
                            # ...
            parameters:
                # ...
            responses: 
                x-42c-local-strategy:
                    x-42c-strategy:
                        protections:
                            - x-42c-security-headers_0.1:       # response level
                                # ...
                200: 
                    x-42c-local-strategy:
                        x-42c-strategy:
                            protections:
                                - x-42c-security-headers_0.1:   # status level
                                    # ...

The extension x-42c-local-strategy defines a list of protections that API Firewall applies to a particular API operation or response, in the order in which they are listed. The protections are applied as strategies, so x-42c-strategy is always nested inside this extension.

You can choose when a local strategy is applied depending where in your API definition you add it. The scope of the extension changes as follows:

Local protections override protections applied on a higher level in your API. For example, if you have applied a protection both to a response and a particular HTTP status code, the protection applied to the status code will override the protection applied to the response.

Example

/api/user/info:
    get:
        x-42c-local-strategy:
            x-42c-strategy:
                protections:
                    - x-42c-request-limiter_0.1:
                        key: req_limiter_login
                        hits: 2
                        window: 10
                    # ...

The extension x-42c-request-strategies declares protections on a global level, meaning that they are applied to all incoming requests to your API. The protections are applied as strategies, so x-42c-strategy is always nested inside this extension.

You can further specify which operations (GET, POST, DELETE...) you want to apply the protections to. In this case, the protections are only applied to the listed operations. For more granular control, use the extension x-42c-local-strategy to apply protections locally to individual paths or operations.

Example

#...
x-42c-request-strategies:
    - operations:
        - post
        - put
      x-42c-strategy:
        protections:
            - x-42c-request-limiter_0.1:
                key: req_limiter_login
                hits: 3
                window: 15
            # ...

The extension x-42c-response-strategies declares protections on a global level, meaning that they are applied to all responses sent back to the API consumers. This can be useful to prevent data leaks or enhance requests, for example, with security headers. The protections are applied as strategies, so x-42c-strategy is always nested inside this extension.

You can further specify which responses you want to apply protections to. In this case, the protections are only applied to the responses listed for it. You can define a list of HTTP status codes as explicit codes (200, 404, 500...) or a range (1XX, 2XX, 3XX, 4XX, 5XX), or even default. Protections defined for explicit codes override protections defined for a range.

For more granular control, use the extension x-42c-local-strategy to apply protections locally to individual responses or statuses.

Example

#...
x-42c-response-strategies:
    - status:
        - default
        - 200
        - 5XX
      x-42c-strategy:
        protections:
            - x-42c-security-headers_0.1: 
                hsts.max_age: 7200
                csp.policy: 'default-src: ''self''; upgrade-insecure-requests; block-all-mixed-content'
                mode: add-replace
            # ...

The extension x-42c-strategy contains the list of protections that API Firewall applies to requests or responses, in the order in which they are listed. The extension indicates where a section on security measures begins. Protections are applied as strategies, so you always define them under this extension.

The extension x-42c-strategy is always nested inside the extensionx-42c-local-strategy, x-42c-request-strategies, or x-42c-response-strategies. This way, API Firewall always knows if the protections apply on a global level to all requests and responses, or locally to a particular API operation or response. You never use x-42c-strategy on its own.

For the descriptions of available protections and their x-42c extensions, see Protections.

Example

/api/user/info:
    get:
        x-42c-local-strategy:
            x-42c-strategy:
                protections:
                    - x-42c-request-limiter_0.1:
                        key: req_limiter_login
                        hits: 2
                        window: 10
                    # ...

The basic rules for the extension syntax apply to references to the reusable protections:

/api/user/info:
    get:
        x-42c-local-strategy:
            x-42c-strategy:
                protections:
                    - $ref: '#/x-42c-components/x-42c-protections/my-reusable-ratelimiting'
                    - $ref: '#/x-42c-components/x-42c-protections/my-reusable-jwt'
                    # ...

Different systems take different approach to the case of paths in a file system:

• If file paths are case-sensitive, this means paths like /Sample, /sample, and /SAMPLE are all treated as three separate paths.
• If file paths are caseless (not case-sensitive), this means that /Sample, /sample, and /SAMPLE are treated as one and the same path.

If your API exposes caseless paths of a file system (for example, client-side, server-side, or from a cdn) in its OpenAPI definition, you can use this extension in your API definition to indicate to API Firewall how the case in paths should be treated:

• If set to false, API Firewall considers file paths in the API to be case-sensitive. This is the default option.
• If set to true, API Firewall considers file paths in the API to be caseless.

You can apply this extension to the global level in your API definition:

openapi: 3.0.0
info:
    # ...
x-42c-caseless-paths: true
servers:
    # ...

Cross-origin resource sharing (CORS) allows a server to indicate to browsers to load resources from another origin (such as domain or port) than the one that the server itself exposes. As part of CORS, browsers can send an OPTIONS request to query the supported methods before sending the actual request to access the resources.

To simplify CORS handling, you can use this extension to direct API Firewall to let these pre-flight OPTIONS requests proceed to the protected API even if the OPTIONS method was not explicitly defined in its OpenAPI definition. When enabled, API Firewall allows the incoming OPTIONS request to pass through to the API and then forwards the outgoing response from the API back to the API consumer without the processing them in any way.

You can add the extension to your API globally at the top level, or locally to individual operation objects as required.

openapi: 3.0.0
info:
    # ...
x-42c-forward-options: true
servers:
    # ...