API Response Caching

API response caching stores the serialized output of an API request rather than only the underlying data. This can be highly effective because it avoids not just data fetches but also response assembly, pagination shaping, serialization, and sometimes authorization-adjacent filtering work. The danger is that API responses are often shaped by many request dimensions at once.

That means the cache key and scope model must be explicit. Query parameters, headers, locale, tenant, auth context, and representation version may all determine whether two requests can safely share one response.

    flowchart LR
	    A["Request path + params + headers + scope"] --> B["API response cache key"]
	    B --> C["Serialized JSON response"]

Why It Matters

API response caches are often more immediately useful than lower-level object caches because many clients care about the final payload shape, not the raw records. But the same usefulness makes them risky. A response cache that ignores auth or query variation can return fast and dangerously wrong data.

Where It Fits Best

This pattern is strong when:

• many clients request the same resource shape repeatedly
• response assembly is nontrivial
• the representation is safe to reuse within a clearly modeled scope
• the cache contract is expressed in HTTP or a similar request-key model

It is weaker when each request is highly user-shaped or when the response is sensitive to many low-visibility context dimensions.

Example

This HTTP contract shows a cacheable API response with explicit representation and freshness semantics.

1Cache-Control: private, max-age=30, stale-while-revalidate=60
2ETag: "account-summary-v12"
3Vary: Authorization, Accept-Language

What to notice:

• private prevents unsafe shared caching of user-scoped output
• Vary communicates key dimensions that change the response
• the API response is cached as a representation, not merely as raw data

Common Mistakes

• caching authenticated responses in a shared scope accidentally
• omitting query or header dimensions that materially change the payload
• assuming object-level invalidation automatically solves response-cache correctness
• using response caching where almost every request is effectively unique

Design Review Question

Why can API response caching be more dangerous than entity caching even when both speed up the same feature?

The stronger answer is that response caching captures the final representation, which often depends on more context dimensions than one domain entity does. If those dimensions are not encoded correctly, the system can over-share a finished response.

Quiz Time