REST API Caching: Cache-Control, ETag and 304

The fastest request is the one never sent; the next fastest returns no body. HTTP has caching built in – browsers, CDNs and proxies all understand it – and REST's "cacheable" constraint exists to take advantage of it. Two tools do most of the work: Cache-Control says how long a response may be reused, and ETags let a client ask "has this changed?" and get a tiny 304 Not Modified when it hasn't.

Cache-Control

ETags and conditional requests

// server.js
import express from 'express';
import { createHash } from 'node:crypto';

const app = express();
app.use(express.json());
app.set('etag', false);                                          // we'll set our own ETags

let catalogue = { version: 1, courses: ['REST API', 'React.js', 'Next.js'] };
const etagOf = (body) => `"${createHash('sha1').update(JSON.stringify(body)).digest('hex').slice(0, 16)}"`;

app.get('/api/catalogue', (req, res) => {
  const etag = etagOf(catalogue);
  res.set({ ETag: etag, 'Cache-Control': 'public, max-age=60' });
  if (req.get('If-None-Match') === etag) {
    return res.status(304).end();                                // unchanged: no body at all
  }
  res.json(catalogue);
});

app.post('/api/catalogue/courses', (req, res) => {
  catalogue = { version: catalogue.version + 1, courses: [...catalogue.courses, req.body.title] };
  res.status(201).json(catalogue);
});

app.get('/api/me/payment-methods', (req, res) => {
  res.set('Cache-Control', 'no-store').json([{ brand: 'visa', last4: '4242' }]);
});

app.listen(process.env.PORT ?? 3000);

// client.js
const API = 'http://localhost:3000/api/catalogue';
let cached = null;                                               // a tiny client-side cache

async function getCatalogue() {
  const headers = cached ? { 'If-None-Match': cached.etag } : {};
  const res = await fetch(API, { headers });
  if (res.status === 304) {
    console.log(`304 Not Modified – reuse cached copy (v${cached.body.version}), 0 bytes downloaded`);
    return cached.body;
  }
  const body = await res.json();
  cached = { etag: res.headers.get('ETag'), body };
  console.log(`200 OK – downloaded v${body.version}, ETag ${cached.etag}, Cache-Control: ${res.headers.get('Cache-Control')}`);
  return body;
}

await getCatalogue();                                            // first call: full response
await getCatalogue();                                            // unchanged: 304
await fetch('http://localhost:3000/api/catalogue/courses', {
  method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ title: 'TypeScript' }),
});
const latest = await getCatalogue();                             // changed: new ETag, full response
console.log(latest.courses.join(', '));

$ node client.js
200 OK – downloaded v1, ETag "3c73b3730b128abd", Cache-Control: public, max-age=60
304 Not Modified – reuse cached copy (v1), 0 bytes downloaded
200 OK – downloaded v2, ETag "84656e92cbd72110", Cache-Control: public, max-age=60
REST API, React.js, Next.js, TypeScript

• An ETag is a fingerprint of the representation – a hash of the content or a version number. Strong ETags ("…") mean byte-identical; weak ones (W/"…") mean semantically equivalent.
• Express already adds weak ETags and answers If-None-Match for you; the manual version above shows what happens underneath, and lets you base the ETag on a database version column instead of hashing the body.
• Last-Modified / If-Modified-Since work the same way with timestamps, at one-second precision.

What to cache

Practice

Summary