Skip to content
API Design Learn/Production REST I: Performance & Reliability
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

HTTP Caching

5 min read

You'll learn to

  • -Use ETag and If-None-Match to let clients avoid re-downloading unchanged resources
  • -Choose appropriate Cache-Control directives for different kinds of resources
  • -Estimate the bandwidth saved by conditional requests
  • -Use If-Match with an ETag to stop two clients overwriting each other

HTTP has built-in caching primitives that let a client (or an intermediate cache/CDN) avoid re-fetching a resource that hasn't changed - using them well can eliminate a large fraction of an API's traffic for free, without any application-level caching layer.

An Analogy: Yesterday's Newspaper

You subscribe to a newspaper, and every morning you could ask the newsagent to hand over a fresh copy. A smarter habit: you tell them the edition number you already have, and they say same edition, nothing new, and save you the weight of carrying it again. Other things have a best-before date, like milk, which you can use without asking anyone until it expires. And some things you are told never to keep at all.

  • -The edition number is the ETag, and showing it with a request is If-None-Match.
  • -Same edition, nothing new is the 304 Not Modified response.
  • -The best-before date is max-age: use the stored copy without asking until then.
  • -Ask before using, even if you have a copy, is no-cache. Never keep a copy is no-store.

ETag: A Fingerprint for the Current State

ETag lets the client ask "has this changed since I last saw it?"
# First request - server returns the resource plus a fingerprint
GET /products/42
HTTP/1.1 200 OK
ETag: "a1b2c3d4"
{"id": 42, "name": "Widget", "price": 19.99}

# Later request - client sends back the fingerprint it has
GET /products/42
If-None-Match: "a1b2c3d4"

# If nothing changed: no body needed, just confirm the cache is still valid
HTTP/1.1 304 Not Modified

# If something changed: full response, with a new ETag
HTTP/1.1 200 OK
ETag: "e5f6a7b8"
{"id": 42, "name": "Widget", "price": 24.99}

A 304 Not Modified response has no body - the client already has the current representation cached and the server is just confirming it's still valid, saving the bandwidth and processing cost of re-sending unchanged data. The ETag itself is typically a hash of the resource's content or a version number, and it must change whenever the resource's meaningful content changes.

What It Saves

Put numbers on it. A product response is 5 KB, and the endpoint gets 1,000 requests a second, which is 5 MB a second. If 90% of those requests arrive with a matching ETag, they are answered with a 304 of around 0.3 KB of headers. The traffic becomes 100 x 5 KB + 900 x 0.3 KB = 500 + 270 = 770 KB a second, about 85% less. The server still receives each request, but it can often answer the version check without doing the expensive work of building the response. With max-age=3600, a client that has a fresh copy does not send the request at all, so those requests vanish entirely.

Cache-Control: Who Can Cache This, and for How Long

Different resources want different caching policies
# A public, rarely-changing resource - cache aggressively, even in shared caches
GET /products/42
Cache-Control: public, max-age=3600

# User-specific, sensitive data - never cache in a shared/intermediate cache
GET /users/me/account
Cache-Control: private, no-store

# Content that must always be revalidated before use, even if cached
GET /orders/501/status
Cache-Control: no-cache
  • -public: any cache (browser, CDN, proxy) may store this response.
  • -private: only the end client may cache it - not a shared/intermediate cache, since the response may be user-specific.
  • -no-store: never cache this at all, anywhere - for genuinely sensitive data.
  • -no-cache: caching is allowed, but the cache must revalidate with the server (via ETag) before using the cached copy - not the same as no-store, despite the confusingly similar name.
  • -max-age: how many seconds a cached response can be used without revalidation.

Vary and Shared Caches

A shared cache, such as a CDN, stores one response per URL, which is wrong if the response depends on something else in the request, such as the language the client asked for. The Vary header names those request headers: Vary: Accept-Language tells caches to keep a separate copy for each language. Forgetting Vary is how one user ends up seeing another user's French or personalized page. For anything that depends on who is asking, use private or no-store.

A Second Use for ETags: Preventing Lost Updates

Two people open the same record and both edit it. The second to save would silently overwrite the first. The ETag lets the server detect that. The client sends the ETag it received along with its update, in an If-Match header, and the server applies the update only if the resource still has that version:

The resource changed since this client read it (its ETag is no longer a1b2c3d4), so the update is refused instead of overwriting the other change
PUT /products/42
If-Match: "a1b2c3d4"
{"id": 42, "name": "Widget", "price": 24.99}

HTTP/1.1 412 Precondition Failed

The client then fetches the current version, shows the conflict, and tries again. This is optimistic concurrency: no locks, and conflicts are caught only when they actually happen.

The most common caching mistake is treating every response identically - a product catalog page and a user's private account balance have very different correct caching policies, and applying one blanket Cache-Control header across an entire API usually gets at least one of them wrong.

Interview Signal is part of Pro

See a real weak answer next to a real strong one for this exact topic.

Quiz is part of Pro

Test what you just read with a short quiz, and bank the XP.

Ready to Build This?

Design The Cache Architect in the API Design Lab's Production Patterns act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!