2026-09-04 · 8 min read
- http
- caching
- api-design
HTTP freshness controls let a cache reuse a response without contacting the origin for a period. Validators support revalidation after that period: the client presents an ETag or modification date, and the server decides whether the selected representation has changed.
A 304 Not Modified response does not contain a replacement representation. The recipient combines its stored body with metadata from the revalidation response according to HTTP rules, which makes the identity and state of the cached entry essential to debugging.
Choose validators for the representation
A strong ETag supports byte-level equivalence for operations that require it, while a weak ETag marks semantic equivalence without promising identical bytes. Last-Modified is useful when the resource has a trustworthy modification time and one-second precision is sufficient.
- Generate validators from stable version data or representation bytes.
- Do not reuse one strong validator for different encoded representations.
- Keep validator behavior consistent across application instances.
- Change the validator whenever the represented content changes.
Build the correct cache key
The request target is only the start of a cache key. Content negotiation, localization, compression, and selected request headers can produce different representations; Vary communicates relevant dimensions to shared caches.
Private or authorization-dependent content needs deliberate cache controls. Never rely on an ETag alone to prevent one user's representation from being served to another user.
- Keep Vary dimensions necessary and bounded.
- Separate public, private, and non-cacheable responses.
- Normalize request targets only according to the application contract.
- Document CDN query-string and header key policies.
Process preconditions in the right order
For safe retrieval, If-None-Match commonly requests revalidation and can produce 304. For state-changing operations, If-Match can prevent overwriting a resource that changed since it was read and typically produces a precondition failure when stale.
Use the HTTP specification's precedence rules when several conditional headers appear. Avoid translating every precondition failure into an ordinary cache miss because update concurrency and retrieval freshness protect different operations.
Test every delivery layer
Use Flashman's URL tool for exact request targets, hash tool to identify synthetic bytes, timestamp converter for modification boundaries, diff to compare headers and bodies, and JSON formatter for sanitized cache events.
Test cold and warm caches, strong and weak tags, changes within one second, compression and language variants, origin and CDN revalidation, purges, failed origins, authorization, range requests, and deployments where old and new instances overlap.