# Headers in OpenAPI best practices

# OpenAPI Headers

A map of header names to [Header Objects](/openapi/paths/operations/responses/headers) or [References](/openapi/references) that define headers in [Response Objects](/openapi/paths/operations/responses#response-object) or [Encoding Objects](/openapi/paths/operations/requests#encoding-object).

In this simplified example, the server returns three [Header Objects](/openapi/paths/operations/responses/headers) with the names `X-RateLimit-Remaining`, `Last-Modified`, and `Cache-Control`:

```yaml
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.