[ADP-124] Cache-Control

Overview

The Cache-Control HTTP header field is used to specify directives for caching mechanisms in both requests and responses. Proper use of caching can significantly improve the performance and scalability of an API by reducing the load on the server and minimizing network traffic.

Guidance

MUST use Cache-Control headers appropriately to optimize API performance and reduce server load.
SHOULD set reasonable max-age values based on the frequency of resource changes.
MUST use no-store for responses containing sensitive or personal information.
SHOULD leverage no-cache for frequently updated resources to ensure freshness while still allowing caching.
SHOULD use the Vary header in conjunction with Cache-Control to specify which headers affect the caching behavior.
MUST consider the implications of caching on API versioning and updates.
Balance between freshness and server load when setting cache durations.
Consider the needs of different clients (e.g., mobile vs. web) when setting cache policies.
Regularly review and update caching strategies as your API evolves.

Key Directives

For Responses

max-age=<seconds>: Specifies the maximum amount of time a resource is considered fresh.
s-maxage=<seconds>: Similar to max-age, but applies only to shared caches.
public: Indicates that the response may be cached by any cache.
private: Indicates that the response is intended for a single user and must not be stored by a shared cache.
no-cache: Requires validation with the origin server before using a cached copy.
no-store: Indicates that the response must not be stored in any cache.
must-revalidate: Cache must verify the status of stale resources before using them.

For Requests

no-cache: Requires the server to validate the resource before using a cached copy.
no-store: Requests that the response not be stored in any cache.
max-age=<seconds>: Indicates that the client is willing to accept a response whose age is not greater than the specified time in seconds.

Best Practices

Use max-age Appropriately: Set a reasonable max-age value based on how frequently your resource changes.
Leverage no-cache for Dynamic Content: For frequently updated resources, use no-cache to ensure freshness while still allowing caching.
Apply no-store for Sensitive Data: Use no-store for responses containing sensitive or personal information.
Utilize public and private: Use public for responses that can be cached by shared caches, and private for user-specific responses.
Consider s-maxage for CDNs: When using a CDN, leverage s-maxage to set different cache durations for the CDN and the browser.
Implement Conditional Requests: Use ETags or Last-Modified headers in conjunction with Cache-Control for efficient validation.

Example

http

Cache-Control: max-age=3600, must-revalidate, public

This example sets the maximum age to one hour, requires revalidation of stale resources, and allows public caching.

OpenAPI Example

yaml

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Get user information
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          headers:
            Cache-Control:
              description: Cache-Control header
              schema:
                type: string
                example: max-age=3600, must-revalidate, public
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string

This OpenAPI example demonstrates how to document the Cache-Control header in an API specification using OpenAPI 3.1.0.

[ADP-124] Cache-Control ​

Overview ​

Guidance ​

Key Directives ​

For Responses ​

For Requests ​

Best Practices ​

Example ​

OpenAPI Example ​

Related ADPs ​

References ​