Make Cache Invalidation Part of the Data Contract

Define the cache contract across every layer

A cacheable representation needs a contract: key dimensions, validator, maximum freshness, mutation invalidation, stale-on-error policy, and owner. Model every layer together because purging a CDN does not by itself invalidate browser caches or application object caches. Use RFC 9111: HTTP Caching as the protocol baseline, then use MDN’s HTTP caching guide for implementation-oriented examples and operational context.

Trace a document update through every cache

Version immutable assets in URLs. For mutable resources, use validators such as ETag or Last-Modified where appropriate, then revalidate. A document update commits its version, invalidates application keys, and purges CDN variants. Authorization-sensitive responses need correct private or shared directives and Vary dimensions. MDN’s HTTP caching guide is especially useful here because it distinguishes private caches from shared caches and explains how managed caches can be purged explicitly, while RFC 9111 defines freshness, validation, and reuse behavior.

Model every cache layer

For each representation, list browser, CDN, gateway, application, and database-derived caches. The contract names the complete key, validator, maximum age, invalidation trigger, and acceptable stale-on-error window. Include authorization dimensions: a response that varies by tenant or permission cannot share a key that omits them.

Use immutable URLs for versioned assets. For mutable documents, return a validator and require conditional writes where lost updates matter. When an update commits, publish the new document version, delete object-cache entries, and purge CDN variants. If your purge mechanism can be retried, design it to be idempotent so a retry is harmless.

This is also where teams should be precise about private versus shared reuse. RFC 9111 defines private and shared caches, and MDN’s HTTP caching guide notes that personalized responses belong in a private cache unless you have explicitly designed a safe shared-cache strategy. A content version alone is not enough if the representation also varies by audience.

Prove the stale bound

Create document version 7, warm every layer, update to version 8, then read through each route until all responses converge. Record the Age header, cache status, validator, and observed version. Repeat with the purge service unavailable and verify the documented stale limit rather than assuming invalidation succeeded.

Test a permission removal separately. An old public representation must not remain readable merely because its content did not change. Pick one sensitive endpoint and write its cache contract beside the API schema; if the team cannot name the slowest invalidation path, disable shared caching until it can. Include authenticated and anonymous variants in the rehearsal; a correct document version served under the wrong audience key is still a cache failure.

Review date: 2026-09-06