Surrogate Keys
Surrogate keys are cache tags attached to HTTP responses so a CDN can purge every cached object that shares a label without knowing each URL. An edge gateway can emit Surrogate-Key headers on catalog or CMS API responses, then purge by product ID or locale when upstream data changes.
Technical Architecture & Deep-Dive
URL-only invalidation breaks down when one record appears under many paths or query variants. Surrogate keys group variants by business identity, such as `product-42` or `locale-en`.
On cacheable GET gateways, workers add surrogate keys after fetching upstream JSON, store them in the CDN metadata, and call the provider purge API when webhooks fire. Pair keys with normalized cache keys so irrelevant query params do not fragment the cache while still allowing precise invalidation.
Key Architectural Benefits
Implement Surrogate Keys at the Edge
Deploy lightweight API aggregation, edge caching, and secret injection in minutes without Docker containers or complex servers.
Frequently Asked Questions
Q:Are surrogate keys visible to browsers?
They are primarily for shared caches. Some platforms strip them at the client edge. Design purges through your CDN or edge provider APIs.
Related Architecture Concepts
Cache invalidation is the process of removing or marking cached data as stale so subsequent requests fetch fresh content from the origin. Strategies include time-based expiry with TTLs, explicit purges by URL or tag, and event-driven invalidation triggered by data changes.
A cache key is the unique identifier a cache uses to store and look up a response. It is typically built from the request URL and may include query parameters, selected headers, or user attributes. Two requests with the same cache key receive the same cached response.
A Content Delivery Network (CDN) is a globally distributed network of servers that caches and serves content from locations close to users. By answering requests from a nearby point of presence instead of a distant origin, a CDN reduces latency, offloads origin traffic, and absorbs traffic spikes.
The HTTP Vary response header lists request headers that must participate in the cache key because they change the response body. For APIs, common examples include Accept-Encoding, Accept-Language, and sometimes Authorization when responses are user-specific but still edge-cacheable per user.
Ready-to-Use Edge Recipes
To cache contentful delivery api at edge avoid limits, put a TTL cache on your RealComposer pipeline. 300s TTL on composed entry responses at Cloudflare edge. Shared edge cache absorbs repeat traffic before it reaches Contentful.
To contentful and algolia search cache edge, put a TTL cache on your RealComposer pipeline. Cache composed search hits for popular queries. Shared edge cache absorbs repeat traffic before it reaches Contentful and Algolia.