Skip to content
Platform Status

Responses

Headers in OpenAPI best practices

OpenAPI Headers

A map of header names to Header Objects or References that define headers in Response Objects or Encoding Objects.

In this simplified example, the server returns three Header Objects with the names X-RateLimit-Remaining, Last-Modified, and Cache-Control:

paths:
  /drinks/{productCode}:
    get:
      responses:
        "200"
          description: A drink.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Drink"
          headers:
            X-RateLimit-Remaining:
              description: The number of requests left for the time window.
              schema:
                type: integer
                example: 99
            Last-Modified:
              description: The time at which the information was last modified.
              schema:
                type: string
                format: date-time
                example: '2024-01-26T18:25:43.511Z'
            Cache-Control:
              description: Instructions for caching mechanisms in both requests and responses.
              schema:
                type: string
                example: no-cache

Header Object in OpenAPI

Describes a single header.

The name of a header is determined by the header’s key in a headers map.

Header Object Fields

Field
description
Type
String
Description
A description of the header. This may contain CommonMark syntax to provide a rich description.
Required
required
Type
Boolean
Description
Whether the header is required. Defaults to false.
Required
deprecated
Type
Boolean
Description
Whether the header is deprecated. Defaults to false.
Required
schema
Description
A schema or reference to a schema that defines the type of the header. This is required unless content is defined. Note: OpenAPI 3.0.x supports OpenAPI Reference Objects here as a value. OpenAPI 3.1.x uses the JSON Schema Referencing format.
Required
content
Type
Map[string, Media Type Object]
Description
A map of Media Type Objects that define the possible media types that can be used for the header. This is required unless schema is defined.
Required
x-*
Description
Any number of extension fields can be added to the header object to be used by tooling and vendors.
Required