What is API Caching? Headers, Layers and Invalidation

What is API caching?

API caching means storing an API response so that later identical requests are answered from the stored copy instead of running the work again. The copy can live in the client, a CDN, an API gateway or your own application. A cached response is faster and spares the backend, but it can also be out of date, so every caching decision is a trade-off between speed and freshness.

Where responses get cached

• Client or browser cache. A private cache tied to one user. It saves the network round trip entirely.
• CDN or reverse proxy. A shared cache near users. See content delivery networks. It only helps for responses that are the same for many users.
• API gateway. A shared cache in front of your services, controlled by the gateway's own rules.
• Application cache. In-process memory or a store such as Redis. Often you cache the expensive query or computed value rather than the whole HTTP response.
• Database cache. Buffers and query caches inside the database, mostly automatic.

The HTTP headers that control it

RFC 9111 defines how HTTP caches behave. The main response headers are:

• Cache-Control: max-age=60: the response stays fresh for 60 seconds. s-maxage sets freshness for shared caches only.
• Cache-Control: no-cache: the response may be stored but must be revalidated with the origin before each reuse. It does not mean "do not cache".
• Cache-Control: no-store: no cache, private or shared, should store the response.
• Cache-Control: private: only a private cache such as the browser may store it. public allows shared caches, and is needed only when the request carried an Authorization header.
• ETag and If-None-Match: the client sends the stored validator, and the server answers 304 Not Modified with no body if nothing changed.
• Vary: names the request headers that change the response, such as Accept-Language, so each variant is cached separately.
• stale-while-revalidate and stale-if-error: extensions from RFC 5861 that let a cache serve a stale copy while it refreshes, or when the origin fails.

If you set no freshness information at all, caches may still apply heuristic freshness, typically a fraction of the time since Last-Modified. Set Cache-Control explicitly instead. The MDN HTTP caching guide has worked examples.

Example

A public endpoint, GET /api/v1/products, changes a few times an hour. It can answer with Cache-Control: public, max-age=60 and an ETag, so a CDN absorbs most reads and clients revalidate cheaply. A personalised endpoint, GET /api/v1/me, should send Cache-Control: private, no-cache with an ETag: the browser may keep it, but must check with the server first, and no shared cache stores it. Cache keys include the full URL, so a paginated list needs the page or cursor in the query string; see API pagination.

Strategies and invalidation

• Cache-aside. The app checks the cache, loads from the source on a miss and stores the result. The simplest and most common pattern.
• Write-through. Writes update the cache and the source together. Reads stay consistent, writes get slower.
• TTL expiry. Let entries expire. Simple, but data can be stale for up to the TTL after a change.
• Purge on change. Delete the affected keys or tags when the data changes. Precise, but every writer must know what to purge.
• Versioned URLs. Put a version or content hash in the URL so a change creates a new cache key.

Invalidation is where most caching bugs live. Our guide on cache invalidation in performance testing shows how stale and cold caches distort results.

Common mistakes

• Letting personalised responses into a shared cache. Mark them private. A cookie alone does not make a response private.
• Missing or too broad Vary. Forgetting it serves the wrong variant. Varying on User-Agent fragments the cache so much it rarely hits.
• Caching errors. A 500 stored with a long freshness keeps failing for everyone. Give error responses short or no freshness.
• Cache stampede. When a hot key expires, many requests miss at once and hit the origin. Use a lock on refill, refresh ahead, or stale-while-revalidate.
• Assuming a POST is cached. RFC 9111 allows caching methods other than GET only if the method permits it and defines how to build a cache key, and in practice caches rarely store POST responses. Idempotency is about safe retries, not cacheability.
• Not measuring. Without hit rate and origin load per endpoint, you cannot tune a TTL.

Testing and monitoring a cache

Test caching two ways. Functionally, send the same request twice and check the headers and timing: a cached answer should be faster and carry the freshness headers you intended. Under load, run the endpoint with the cache warm and with cache-busting parameters, and compare response times and the load reaching your origin in your own metrics. You can start with a free API load test. After release, API monitoring keeps watching: LoadFocus API monitoring can assert on the status code, body, headers and response time, so a deploy that drops Cache-Control or makes a cached endpoint slow gets flagged. Free checks run every 5 minutes. Rate limits interact with caching too, because hits served by a cache usually never reach the limiter; see common causes of API rate limiting.

FAQ: API Caching

What should I cache first?

Start with read endpoints that are slow, requested often and change rarely, and whose response is the same for many users. Measure latency and request volume per endpoint to choose.

What is the difference between no-cache and no-store?

no-cache lets a cache store the response but forces revalidation with the origin before each reuse. no-store tells caches not to store the response at all.

Can I cache POST requests?

Rarely. HTTP caches mainly store responses to GET. Some APIs cache search-style POSTs in the application layer with an explicit key, but a CDN or browser will not do it for you by default.

Is a CDN the same as API caching?

No. A CDN is one place where caching happens, at the edge. API caching covers every layer, from the browser to the database.

How do I cache a GraphQL API?

Queries usually travel in a POST body, so URL-based caching does not apply. Common options are persisted queries sent as GET, or caching at the resolver or application level.

How do I know a response came from the cache?

Compare timing, check the Age header and any cache status header your CDN adds, and watch whether the request reaches your origin logs.