Caching and ETags

Why cache at all

Much of what an API returns to you does not actually change on every single call. Re-fetching the very same unchanged resource over and over wastes time, bandwidth, and precious rate-limit allowance for no benefit whatsoever. Caching stores a response so that you can reuse it directly instead of asking for it again, and HTTP comes with built-in machinery to make doing this both easy and safe.

Done well, caching makes an integration noticeably faster and lighter while still keeping the data you act on fresh and correct. The whole trick lies in knowing when a cached copy is still valid and when it genuinely must be refreshed — and that, conveniently, is exactly what the standard caching headers are there to tell you on every response.

Cache-Control

The Cache-Control header carries the rules that govern reuse, and learning its common directives goes a long way. A directive such as max-age states how many seconds a response stays fresh; no-cache means you may store the response but must revalidate it with the server before reusing it; and no-store forbids caching the response entirely, which matters a great deal for sensitive data you must never keep.

Cache-Control: max-age=60

Within the freshness window the header grants, you can serve your stored copy directly with full confidence. Once that window lapses, however, the response is considered stale and needs revalidating before you trust it again, rather than being silently reused as though nothing had changed in the meantime.

ETags as validators

An ETag is an opaque tag that the server attaches to a response to identify that one specific version of the resource. Whenever the underlying resource changes in any way, its ETag changes too. You store that ETag alongside the cached body, and you then use it to check, very cheaply, whether the copy you are holding is still the current one.

The mental model that helps most is to think of an ETag as a fingerprint of the response. Rather than bluntly asking the server to "send me the resource" all over again, you can instead ask it to "send the resource only if it now differs from the version carrying this fingerprint" — turning what would have been a full download into a tiny, near-free check whenever nothing has actually changed since last time.

Conditional requests

You revalidate a stale copy by making a conditional request, sending your stored ETag back to the server in an If-None-Match header. If the resource is unchanged, the server replies with 304 Not Modified and no body at all, and you simply reuse the cached copy you already have. If it has changed, you instead receive a fresh 200 carrying the new data along with a new ETag to store.

GET /v1/cases/42 HTTP/1.1
If-None-Match: "a1b2c3"

A 304 is genuinely a win for you: you have confirmed your data is fresh while transferring almost nothing at all over the network, which is wonderfully gentle on both latency and your standing rate-limit budget across many such checks.

Avoiding stale data

Caching is ultimately a balancing act that rewards a little care. Cache too aggressively and you risk acting on out-of-date information that has quietly moved on; ignore caching altogether and you waste time, bandwidth, and rate limit on needless re-downloads. The reliable middle path is to honour the server's directives faithfully, revalidate whenever a response has gone stale, and never cache anything the server marks as no-store.

Because conditional requests cut so much redundant traffic, caching turns out to be one of the very best tools for staying comfortably within your limits — see rate limiting explained for how the two reinforce each other in a busy integration.