Invalidation Strategy

## The real question is tolerance, not volatility Engineers instinctively set TTL from how often data changes. That is the wrong input. The right input is **how long a stale answer remains acceptable to the consumer of this API**. A stock level that changes many times per second may still be perfectly serviceable at 15 seconds old on a product page, while a feature flag that changes twice a year may need to take effect within seconds when it does change. Volatility tells you how *often* you will serve something stale; tolerance tells you whether that matters. So the design conversation is: what breaks if a client sees data N seconds old? For a public catalogue, nothing. For a permissions or entitlement response, quite a lot. For a payment status, the user reloads and complains. Write the tolerance down per resource; the TTL falls out of it. ## The freshness directives you are choosing between - `max-age=N` — how long any cache may serve the response without checking back. - `s-maxage=N` — overrides `max-age` for **shared** caches (CDN, reverse proxy) only. This split is the single most useful lever in API caching, because shared caches are purgeable and private browser caches are not. - `private` — only a single user's cache may store it; shared caches must not. - `no-store` — do not persist at all. - `stale-while-revalidate=N` — after expiry, a cache may serve the stale copy for up to N seconds while it refreshes in the background. - `stale-if-error=N` — a cache may serve stale content for up to N seconds when the origin is failing. A short `max-age` plus a generous `stale-while-revalidate` is often the best shape for an API: users almost always get an instant answer, the origin sees one refresh per key per window rather than a stampede, and worst-case staleness stays bounded and explicit. ## A ladder by resource class **Immutable representations.** If the URL uniquely identifies one byte-for-byte version — a content hash, a build id, an immutable revision — cache for a year with `immutable`. There is no invalidation problem because you never need to invalidate; you publish a new URL. This is the cheapest correct caching in existence and worth engineering the URLs for. **Reference and configuration data.** Country lists, category trees, price books. Minutes to hours. These are read constantly and changed rarely, so the hit ratio is enormous and the risk is a delayed rollout of a change — which is exactly what an explicit purge fixes. **Hot collections and detail resources.** Product listings, public profiles, search facets. Seconds to a minute at the shared cache. The economics are dominated by request volume: even a 10-second TTL on a page served ten thousand times a second collapses origin load by orders of magnitude. **User-specific and authorization-dependent data.** Mark `private`, or `no-store` where the content is sensitive. If the response varies by who is asking, a shared cache that ignores that is a data-leak bug, not a performance tradeoff. Where you do cache per-user, be extremely careful about which request attributes the cache key includes. **Write results and status endpoints.** Generally `no-store`. A cached "pending" answer that outlives the transition is a support ticket. ## Long shared TTL plus purge: the strategy that scales The most effective pattern in production APIs is to set an **aggressively long `s-maxage`** and rely on **explicit purge at write time** rather than on expiry. Expiry-driven caching forces you to trade freshness against hit ratio, and you must pick a compromise that is simultaneously too stale for correctness and too short for efficiency. Purge-driven caching breaks the trade: the CDN holds content until you tell it not to, so the hit ratio is near-total, and the propagation delay after a write is the purge latency rather than the TTL. The cost is that you must actually issue the purges, for every representation a write affects, reliably. That is real work, and a purge you forget is unbounded staleness — which is why the TTL still matters as a **safety net**. A long-but-finite `s-maxage` bounds the damage of a missed purge; `s-maxage` of a year with no purge on a mutable resource is a bug waiting to happen. ## Practical guidance Set TTLs per route rather than globally; a single platform default guarantees that some resources are too stale and others are needlessly uncached. Keep the browser's `max-age` short and the CDN's `s-maxage` long, because you can purge one and not the other. Publish the intended staleness in your API documentation so consumers can reason about it. And measure: cache hit ratio, origin request rate, and observed staleness after writes are the three numbers that tell you whether the choice was right.