Skip to content
Last updated

response-contains-header

Requires that response objects with specific HTTP status codes or ranges contain specified response headers.

OASCompatibility
2.0✅
3.0✅
3.1✅

API design principles

In some cases, it is important to design an API so that it consistently returns specific properties in responses. A common example is to return pagination headers for collections. This rule helps achieve the desired consistency across all or some responses in an API.

Configuration

OptionTypeDescription
severitystringREQUIRED. Possible values: off, warn, error.
namesMap (HTTP response code or range, [string])REQUIRED. For a given HTTP response code or range, the corresponding list of expected HTTP response headers.

An example configuration:

rules:
  response-contains-header:
    severity: error
    names:
      2XX:
        - x-request-id
        - x-correlation-id
      '400':
        - Content-Length
        - x-correlation-id

Examples

Given this configuration:

rules:
  response-contains-header:
    severity: error
    names:
      2XX:
        - x-request-id
        - x-correlation-id
      '400':
        - Content-Length
        - x-correlation-id

Example of an incorrect response:

paths:
  /customers/{id}:
    post:
      responses:
        '200':
          description: OK
          headers:
            x-request-id:
              description: The request ID returned in the response.
              schema:
                type: string

Example of a correct response:

paths:
  /customers/{id}:
    post:
      responses:
        '200':
          description: OK
          headers:
            x-request-id:
              description: The request ID returned in the response.
              schema:
                type: string
            x-correlation-id:
              description: The correlation ID for log audit purposes.
              schema:
                type: string

Resources

response-contains-property