Edge Caching Strategies, Cache-Control Directives, and Invalidation
Caching deterministic read responses at the API gateway cuts round-trip latency and shields origin databases, provided cache keys and privacy headers are configured accurately.
HTTP Caching Semantics at the Gateway Edge
Deterministic read endpoints—such as product catalogs and reference configurations—serve identical payloads to thousands of callers. Serving them from API gateway memory eliminates upstream network hops and database queries. Per RFC 9111, shared gateways honor origin `Cache-Control` directives.
Distinguishing `public`, `private`, and `no-store` is essential for security. Responses marked `private` or carrying user-specific `Authorization` headers must never enter a shared cache unless keyed explicitly by verified identity claims.
- Cache only safe, idempotent `GET` and `HEAD` requests by default
- Use `s-maxage` to give shared gateways a distinct TTL from browser `max-age`
- Never cache responses containing `Set-Cookie` in shared pools
- Enforce `Cache-Control: no-store` on financial or credential responses
Cache Key Normalization and Vary Headers
Cache hit ratios drop when unsorted query strings (`?a=1&b=2` vs. `?b=2&a=1`) or tracking parameters fragment keys. Canonicalizing query parameter sorting and stripping non-semantic headers improves edge hit rates immediately.
Declare genuinely varying headers such as `Accept-Encoding` or `Accept-Language` in `Vary`, but avoid high-cardinality headers like `User-Agent` or raw `Cookie` that destroy cache efficiency.
- Sort query parameters canonically and allowlist cache-relevant keys
- Include verified tenant IDs in cache keys for multi-tenant endpoints
- Emit `X-Cache-Status: HIT | MISS | STALE` headers in staging to audit hit rates
Stale-While-Revalidate and Stampede Protection
When a popular entry expires under heavy load, concurrent misses can stampede the origin database. Gateways prevent stampedes via single-flight request coalescing—collapsing identical concurrent misses into one upstream fetch.
With `stale-while-revalidate=30`, requests in the grace window receive the cached payload at memory speed while the gateway refreshes asynchronously. Pairing `stale-if-error` preserves availability during brief upstream 5xx blips.
- Enable single-flight request coalescing on cache misses
- Use `stale-while-revalidate` to hide origin refresh latency
- Configure `stale-if-error` for graceful read degradation
Active Invalidation and Surrogate Keys
Pricing updates or inventory changes often cannot wait for TTL expiration. Origins can attach `Surrogate-Key` tags (such as `product-481`) to cacheable responses.
On update, the backend sends a targeted purge event to the gateway control plane, evicting all tagged routes within milliseconds without flushing unrelated cached items.
API Gateway Caching Directives & Patterns
| Directive / Technique | Behavior at Gateway | Origin Protection | Data Freshness | Ideal Workload |
|---|---|---|---|---|
| `public, s-maxage=60` | Caches in shared gateway for 60 s | High within TTL | Up to 60 s lag | Public reference data & catalogs |
| `private, max-age=60` | Bypassed in shared gateway; browser only | None at edge | Per-user session | User profiles & private account views |
| `stale-while-revalidate=30` | Serves stale while async refreshing | Very high (zero miss wait) | Bounded grace period | High-traffic feeds & dashboards |
| `ETag` + `If-None-Match` | Conditional revalidation (304 Not Modified) | Saves payload bandwidth | Immediate on origin check | Large JSON manifests with low churn |
| `Surrogate-Key` Purge | Event-driven targeted eviction | High (allows longer TTLs) | Near real-time | CMS, pricing, and inventory APIs |
Always strip internal `Surrogate-Key` tagging headers before returning final responses to external clients.
Worked Illustration: Calculating Origin Offload with Edge Caching
This worked illustration models upstream offload when enabling a 30-second `s-maxage` and miss coalescing on a catalog endpoint receiving 2,400 req/s.
- Step 1 (Baseline): Without caching across 500 active SKUs, all 2,400 req/s strike the origin microservice and database.
- Step 2 (Normalization): Sort query keys (`?currency=USD®ion=eu`) and enable single-flight miss coalescing across 4 gateway nodes.
- Step 3 (Miss Math): Each of 500 keys expires once per 30 s per shard, yielding ~(500 × 1) / 30 ≈ 16.7 origin fetches/s.
- Step 4 (Offload Result): Origin load drops from 2,400 req/s to ~17–35 req/s (>98% offload) while median latency falls from 48 ms to <4 ms.
Engineering Illustration Summary: Key normalization plus miss coalescing converts 2,400 req/s of edge load into ~17–35 req/s at the origin.
Edge Caching Safety & Performance Checklist
- Restrict shared gateway caching strictly to `GET`/`HEAD` requests.
- Audit cached routes to confirm `private`, `no-store`, or `Authorization`-bearing responses never leak.
- Normalize query parameter order and strip tracking parameters from cache keys.
- Enable single-flight request coalescing to stop cache stampedes on TTL expiry.
- Add `stale-while-revalidate` and `stale-if-error` on high-traffic read endpoints.
- Verify targeted `Surrogate-Key` invalidation hooks in staging before production release.
Frequently Asked Questions
Can an API gateway cache authenticated endpoints safely?
Only if verified identity claims (like tenant ID or user ID) are explicitly part of the cache key and downstream browsers receive `Cache-Control: private`.
What is the difference between `max-age` and `s-maxage`?
`max-age` applies to browsers and shared caches, whereas `s-maxage` overrides `max-age` specifically for shared proxies and API gateways.
Why does `Vary: *` disable gateway caching?
Per RFC 9111, `Vary: *` signals that uncacheable factors outside standard headers determine the response, blocking reuse.
Does GraphQL POST traffic work with standard HTTP edge caching?
Standard HTTP caches target `GET` requests. GraphQL caching typically relies on Automatic Persisted Queries (APQ) over `GET` or dedicated query-hash plugins.
Primary Standards & Specifications
- RFC 9111 — HTTP Caching (Internet Engineering Task Force, IETF)
- RFC 9110 — HTTP Semantics (Conditional Requests & ETag, IETF)
- OWASP API Security Top 10 (2023) — API3:2023 Broken Object Property Level Authorization