Caching & ETags

HTTP has a powerful caching model built in. Using it well means a client (or a CDN) can avoid re-downloading data that has not changed — often the single biggest performance win an API gets.

Cache-Control: how long is this fresh?

Cache-Control tells caches whether and how long a response may be reused:

Cache-Control: public, max-age=60        # any cache may reuse for 60s
Cache-Control: private, max-age=0        # only the client, must revalidate
Cache-Control: no-store                  # never cache (sensitive data)

While a response is fresh, the client reuses it with no request at all. Once stale, it revalidates.

ETag + If-None-Match: did it change?

An ETag is a validator — a fingerprint of the current representation. On the next request the client sends it back in If-None-Match; if it still matches, the server returns 304 Not Modified with no body:

sequenceDiagram
  participant C as Client
  participant S as Server
  C->>S: GET /articles/42
  S-->>C: 200 OK + ETag: "v7"
  Note over C: later...
  C->>S: GET /articles/42 (If-None-Match: "v7")
  S-->>C: 304 Not Modified (no body)

A matching ETag turns a full response into a tiny 304

Last-Modified + If-Modified-Since is the timestamp-based equivalent. ETags are more precise (they catch any change, not just second-level time changes).

Computing an ETag

JavaScript

function etagFor(resource) {
  const json = JSON.stringify(resource);
  let hash = 0;
  for (let i = 0; i < json.length; i++) hash = (hash * 31 + json.charCodeAt(i)) | 0;
  return '"' + (hash >>> 0).toString(16) + '"';
}

const article = { id: 42, title: 'Hello', version: 7 };
const tag = etagFor(article);
console.log('ETag:', tag);

// Conditional request: client sends back the tag it has.
function handle(ifNoneMatch) {
  return ifNoneMatch === tag ? 304 : 200;
}
console.log('with stale tag:', handle('"old"'));   // 200
console.log('with current tag:', handle(tag));      // 304

Common mistakes

Caching sensitive data by accident Symptom:

Cache-Control: max-age=3600 on /users/\{id\}/profile
A browser or CDN caches user A’s profile and serves it to user B
Set Cache-Control: no-store, private for authenticated resources

An ETag that isn’t stable Symptom:

The ETag is generated from a timestamp — different servers generate different ETags for identical content
The client sends If-None-Match but the server returns 200 every time instead of 304
Generate the ETag from a hash of the content, not a timestamp

💡 Real-world examples

GitHub API:

Every resource carries an ETag — conditional GET avoids re-transferring unchanged data

A 304 on an authenticated request doesn’t count against the rate limit

AWS S3:

The ETag is the MD5 hash of the object content (for non-multipart, non-SSE-KMS uploads)

Conditional GET via If-None-Match makes syncing large numbers of files efficient

Sources: GitHub REST API — best practices, AWS S3 Object metadata (ETag)