The Cache-Control header specifies directives for caching mechanisms in both HTTP requests and responses.

Key response directives

Storage directives

  • no-store: Caches (browser and CDN) must not store any part of the request or response. Essential for sensitive personal or banking data.
  • no-cache: Caches may store the response, but must revalidate it with the origin server (using ETag or If-Modified-Since) before serving it to clients.
  • public: Any cache (browser, proxy, CDN) may store the response, even if authenticated.
  • private: Only single-user caches (the browser) may store the response; shared caches (CDNs) must not.

Expiration directives

  • max-age=<seconds>: Specifies the maximum time in seconds a response is considered fresh in private and shared caches.
  • s-maxage=<seconds>: Overrides max-age specifically for shared caches (CDNs and reverse proxies).
  • stale-while-revalidate=<seconds>: Indicates that caches may serve a stale response while asynchronously fetching a fresh version in the background.

Common API caching patterns

1. Static immutable assets

Cache-Control: public, max-age=31536000, immutable

2. Dynamic authenticated API endpoints

Cache-Control: private, no-cache

3. Highly confidential data

Cache-Control: no-store, max-age=0

How to test with curl

Inspect cache headers with curl:

curl -i https://api.example.test/v1/products/catalog

Key takeaway

The Cache-Control header dictates caching rules for browsers and CDNs. Use no-store for sensitive data, no-cache with validators for dynamic resources, and max-age with s-maxage for public API content.