Surrogate Key

A surrogate key is a unique identifier attached to a cached object at the CDN edge. When the origin data changes, a single API call purges all cached representations—HTML, JSON, mobile, or desktop—associated with that key. This decouples content identity from URL structure, enabling precise cache management without tracking every possible route.

A single surrogate key can be mapped to dozens of cached objects. For example, updating a product price can instantly invalidate:

• The product detail page
• The category listing page
• The search results
• The JSON API response
• The mobile-specific rendering All with one PURGE command, eliminating the complexity of compiling and sending multiple URL lists.

The origin server communicates surrogate keys to the CDN via the Surrogate-Key HTTP response header. A typical header value is a space-separated list: Surrogate-Key: post-42 author-7 category-python. The CDN parses this header, indexes the keys, and stores the mapping. Subsequent purge requests target these keys directly, not the URLs.

Effective surrogate key strategies use a hierarchical naming convention to enable bulk operations. A key like product-1234 can be purged individually, while a prefix-based purge of product-* clears an entire catalog. This pattern supports both surgical precision and broad sweeps, adapting to different invalidation scopes without managing infinite key lists.

Surrogate keys integrate with stale-while-revalidate caching strategies. A purge command marks the content as stale but does not delete it. The CDN serves the stale version to the next user while asynchronously fetching a fresh copy from the origin. This prevents cache stampedes and ensures zero-downtime content updates, even during mass invalidations.

Major CDN providers implement surrogate keys with different limits and APIs:

• Fastly: Native first-class support with no practical key limit per object
• Cloudflare: Available via Cache-Tag header, limited to 30 tags per response
• Varnish: Open-source implementation using xkey VMOD module
• Akamai: Supported through Cache Tagging feature in Property Manager Each requires configuring the origin to emit the appropriate response header.

The process of purging or updating cached content when the origin data changes. While traditional invalidation relies on URL patterns, surrogate key invalidation targets a specific object and all its representations (HTML, JSON, mobile) with a single command. This is the core mechanism that prevents users from receiving stale data.

A Cache-Control directive that allows a CDN to serve a stale cached response immediately while asynchronously fetching a fresh version from the origin. When combined with surrogate keys, a stale-while-revalidate strategy ensures high availability: a purge triggers a background refresh without blocking the user request.

A serverless function running at the edge of a CDN network. Edge functions can dynamically read surrogate key headers from origin responses and attach them to cached objects. They also intercept purge requests, enabling complex invalidation logic—such as purging a product page and its associated category listings—directly at the edge.

A rendering method that pre-builds all HTML pages at build time. In an SSG architecture, surrogate keys are typically embedded as response headers during the build process. When a headless CMS updates a single blog post, the surrogate key allows the CDN to purge only that specific page without rebuilding the entire site.

A hybrid rendering technique that allows updating static pages on a per-page basis without a full site rebuild. ISR relies heavily on surrogate keys to trigger on-demand revalidation. When content changes, a purge command targeting the page's unique key instructs the CDN to fetch the new render immediately.

An architectural pattern that aggregates content from multiple disparate repositories into a unified API layer. Surrogate keys become critical here: a single federated response may contain data from a CMS, a product database, and a user profile service. Tagging the response with multiple keys allows purging when any source system updates.