In 01-04, when we listed REST's six constraints, we said cacheable was one of them and that we would come back to it. The moment has arrived. The Aroma Store API answers GET /v1/coffees in 40 milliseconds, which is perfectly good, except for one detail: the SPA asks for that catalogue every time a user opens the home page, and the catalogue changes once a day. Millions of identical requests, with the same response, consuming database, CPU and bandwidth to contribute absolutely nothing new.

The fastest request is the one that is never made. The second fastest is the one answered with a 150-byte 304 Not Modified. This lesson turns the theoretical constraint into concrete headers and into code inside the project: src/middleware/cache.js, Cache-Control calibrated resource by resource, ETag with conditional requests, and the reunion we have been promising since 03-05, when If-Match and the 412 close the optimistic concurrency circle. After that we will go beyond caching — compression, N+1, partial responses, asynchronous work — and finish with what should come first: measure before optimising.

1. The levels of caching
2. Cache-Control in depth
3. Aroma Store's caching policy
4. Conditional validation: ETag and Last-Modified
5. The complete 304 flow
6. If-Match and the 412: closing the optimistic concurrency circle
7. Implementation: src/middleware/cache.js
8. Vary, content negotiation and CORS
9. Invalidation: the hard problem
10. Server-side caching with Redis and cache-aside
11. Stampede and locking
12. Compression
13. Connections, HTTP/2 and network latency
14. The database: indexes, N+1 and slow queries
15. Partial responses and pagination as a performance measure
16. Asynchronous work with 202
17. Measure before optimising

Between the user and the data there are several opportunities to do no work. Every level that hits saves everything to its right.

Two concepts to distinguish carefully, because a security decision depends on them:

• Private cache: the browser's. It stores one user's responses.
• Shared cache: a CDN, a corporate proxy. It stores responses it serves to many users.

From which comes the most important rule in the whole lesson: any response that depends on who is asking must carry at least Cache-Control: private. If Marta's GET /v1/orders ends up in a CDN without that directive, the next person to ask for /v1/orders could receive Marta's orders. It is a data leak caused by a missing header, and it has happened in production at large companies more than once.

This is the header that governs everything. Its directives, grouped by what they do:

no-cache does not mean "do not cache". It is the most repeated misreading in HTTP. no-cache means "store it, but ask me before using it". The one that prevents storing is no-store. The difference matters a great deal: with no-cache, a response that has not changed is resolved with a 150-byte 304; with no-store, it is transferred in full every time.

stale-while-revalidate is the most underrated directive. With max-age=60, stale-while-revalidate=300, for the first 60 seconds it is served from cache with no questions asked; between second 60 and second 360, the stale copy is served immediately and refreshed in the background. The user never waits. For a catalogue that changes once a day, that is exactly the desirable behaviour.

stale-if-error is free resilience: if your API returns a 503, the CDN keeps serving the last good copy instead of propagating the error. Combined with what we saw in 04-04, it turns a partial outage into an invisible degradation.

Four decisions that deserve justification:

no-cache on /v1/orders, not no-store. Marta's orders change little between visits. With no-cache, the browser keeps the copy and on the next visit sends an If-None-Match; if nothing has changed it receives a 304 with no body. All the traffic is saved while the freshness guarantee is kept, which is the best of both worlds. And private stops a CDN storing it.

no-store on POST /v1/sessions. The response contains the access token. Having it end up on the browser's disk or in a proxy is exactly what we do not want.

no-store on errors. A 429 cached for five minutes turns a one-minute limit into five. A cached 503 outlives the service's recovery.

A year and immutable on images. It only works because the file name contains a hash of the content (cof_001-a3f9.webp): if the image changes, the URL changes, so the old copy is never wrong. It is the fingerprinting pattern, and it is the only safe way to use such long expiry times.

Implemented as parameterisable middleware:

max-age answers "may I use my copy without asking?". When it expires, the question becomes "has it changed?", and that is where the validators come in.

An opaque identifier for a resource's version.

A weak ETag works for the 304 but not for If-Match on writes nor for range requests, precisely because it does not guarantee exact equality. Since Aroma Store is going to use If-Match for optimistic concurrency, we need strong ETags.

Two ways of generating one:

Aroma Store uses both: the version field from 03-05 for individual resources that have it, and the hash for collections and everything else.

The quotes are not decorative: they are part of the header's syntax. An ETag: a3f9 with no quotes is invalid and many intermediaries ignore it, so caching stops working without giving any error at all.

An HTTP date:

It is weaker than the ETag for two reasons: it has a resolution of one second — two changes within the same second are indistinguishable — and many resources have no reliable modification date.

Aroma Store emits both when it has an updatedAt, but the ETag is the main mechanism.

First request. The client has nothing:

Within the 300 seconds: the browser serves its copy without asking. Zero requests, zero latency.

After the 300 seconds: the copy has expired, but the browser has the validator and asks:

If nothing has changed:

No body. 284 bytes become about 150 of headers, and the browser renews its copy's freshness for another 300 seconds.

If the coffee changed (version went to 8):

Three details about the 304 that are often got wrong:

• It carries no body. Sending one is a protocol error.
• It does carry the caching headers (Cache-Control, ETag, Vary): they are what renews the stored copy's validity.
• If-None-Match accepts several ETags separated by commas, plus the * wildcard meaning "if any representation exists".

Here is the reunion we announced in 03-05. If-None-Match is for reading; If-Match is for writing safely.

Nobody has seen an error. The price 15.20 never existed.

If the current version is no longer 7:

The ETag: "v8" on the error response is a valuable design detail: it tells the client what the current version is, so it can re-read, show the conflict to the user and retry with no extra request.

In 03-05 we implemented optimistic concurrency with version inside the JSON. It works, but If-Match is better for five reasons:

The last row is the conceptual key: the client already received the ETag when it read the resource. It does not need to understand what version is, nor extract it from the body: it returns the opaque tag it was given. That is exactly HTTP's design.

And there is an important contract decision: whether or not to require If-Match.

Aroma Store requires it on PUT /v1/coffees/{id} and on PATCH /v1/orders/{id}, because a price or a stock level being wrongly overwritten has real commercial consequences. That forces us to add a new code to the catalogue: precondition_required (428). We note it explicitly, as the project's rule demands — the catalogue only grows — and it has to be documented in openapi.yaml.

The comment in the middle is the subtle point: checking the version in the service is not enough; there is a window between the read and the write. The real guarantee comes from the UPDATE's WHERE version = ?, which is atomic. If-Match contributes the correct HTTP semantics and the early error; correctness still comes from the database.

And Accept-Patch, which we have been emitting since 02-05, goes hand in hand with this: it tells the client which patch format the resource accepts, just as ETag tells it which version it has.

What is missing is the piece that answers the 304 automatically. The strategy: wrap res.json to compute the ETag just before sending and compare it with If-None-Match.

Why conditionalEtag at position 10, right before the routes. It has to wrap res.json before any controller calls it, and at the same time be after everything that can respond on its own (rate limiting, parser), because we do not want to give an ETag to those responses. And why compression at position 7, earlier: compression must wrap the writing of the response as early as possible, and it must not try to compress a 304 that has no body.

A practical note: Express ships its own automatic ETag (app.set('etag', ...)), but it is weak by default, which makes it useless for If-Match. Our middleware replaces it with strong ETags and with explicit control over when they are emitted.

Vary declares which request headers the response depends on. It is what stops a cache serving the wrong response.

The Authorization case deserves an explanation because it looks like the obvious answer and is not. Setting Vary: Authorization would make the cache store one entry per distinct token: since tokens change every 15 minutes, the hit rate would be practically zero and the CDN's memory consumption enormous. The correct way to protect personalised content is Cache-Control: private, which directly prevents a shared cache storing it.

And the cost warning: each header in Vary multiplies the stored variants. Vary: Accept, Accept-Language, Origin with 2 types, 3 languages and 3 origins is 18 copies of the same resource. Declare only what really changes the response.

"There are only two hard things in Computer Science: cache invalidation and naming things." — Phil Karlton

The difficulty is real: you have distributed copies of your data across browsers and CDNs all over the world, and now the price of cof_001 has changed.

The browser's cache cannot be purged. Once you have sent max-age=3600, that browser will serve the copy for an hour and there is nothing to be done. That is why the browser TTLs are short (60 s) and the CDN ones long (300 s with s-maxage): the CDN can be purged.

Purge tags (surrogate keys) are the mechanism that makes this manageable. Each response declares which groups it belongs to:

And when cof_001 changes, the purge goes by tag rather than having to enumerate the dozens of affected URLs (the detail page, the list, the list filtered by origin, the one sorted by price…). Without tags, invalidating collections is practically impossible to do well.

Why event-driven invalidation fits with webhooks. Aroma Store already emits signed events towards SwiftShip (order.paid, order.shipped). The same mechanism works for the cache: when the catalogue service changes a price, it publishes coffee.updated and whoever is subscribed — the CDN, another instance, the back office — purges its own copy. The advantage is decoupling: the service doing the writing does not need to know every cache that exists, only to announce that something changed.

HTTP caching avoids requests. Server-side caching avoids database queries for the requests that do arrive.

What is worth caching in Aroma Store:

The last two rows are as important as the first ones: knowing what not to cache avoids incidents. Caching stock for 60 seconds means selling coffee that does not exist.

The cache-aside pattern (or lazy loading):

Four rules to stay out of trouble:

1. Cache the already-mapped result, not the raw row. That way the object in Redis contains no internal columns: if one day somebody dumps it for debugging, it does not leak price_cents or active.
2. The cache is never a hard dependency. If Redis goes down, the API is slower, it does not fail.
3. Namespace your keys (aroma:cache:), kept separate from the rate limiting's aroma:rl: from 04-04.
4. Invalidate on write, in the same operation that modifies the data.

An important warning: do not cache error objects or exceptions. In the example, if the coffee does not exist an exception is thrown before anything is stored; if the null were cached, a newly created coffee would take five minutes to appear.

The scenario: cof_001 is the most requested coffee and its cache entry expires at 12:00:00. At that instant there are 500 requests in flight. All 500 miss the cache, all 500 query the database and all 500 write the same value.

That is the cache stampede (or thundering herd), and it is especially cruel because it happens precisely on the most popular resources, that is, at the worst possible moment.

Three defences, from least to most effective:

TTL with jitter. Instead of exactly 300 seconds, a random value between 270 and 330. It spreads the expiries out and stops thousands of keys expiring at once. It is one line of code:

Locking. Only one process recomputes; the rest wait briefly and retry the cache:

Early refresh. Store the expiry instant alongside the value and refresh it before it expires, probabilistically. There is never a moment when the key does not exist. It is what stale-while-revalidate does in the HTTP cache, applied to the server.

The saving on JSON is considerable because it is text with a great deal of key repetition:

When not to compress:

• Small responses (below about 1 kB): the overhead exceeds the saving.
• Already-compressed content: images, video, PDF, ZIP.
• When the CPU is the bottleneck and the network has plenty of headroom.
• Historically, responses with secrets alongside attacker-controlled data, because of the BREACH/CRIME attacks. With Authorization: Bearer instead of cookies the practical risk is much lower, but it is worth knowing about.

Brotli compresses better than gzip and every modern browser supports it; most CDNs apply it on their own. If you have a CDN, the usual approach is to let it compress and save that CPU in your process.

Revisiting 01-03 from a performance perspective:

A reminder from 04-04: Node's keepAliveTimeout must be greater than the load balancer's, or sporadic, impossible-to-reproduce 502s will appear.

And the perspective that orders the priorities: on a typical mobile request, network latency dominates everything else. If your API answers in 40 ms and the user is 150 ms away, optimising the SQL query down to 30 ms improves the total by 5%. Cutting five requests down to one (04-01) or serving from a CDN improves it far more. The most profitable optimisation is almost never on the server.

Indexes. Every filter in the contract needs its own:

The order of the columns in a composite index matters: (customer_id, created_at) works for filtering by customer and sorting by date, but not for sorting by date without filtering by customer. And indexes are not free: they speed up reads and slow down writes, because they have to be maintained.

How to verify they are being used:

The N+1, now in the database (in 04-01 we saw it over HTTP):

A security note about the IN: the ? placeholders are generated from the number of items, and the values go as parameters. The ids are never interpolated into the SQL (04-02). And the size of the list has to be bounded, because engines have a parameter limit; with a maximum limit of 100 we are well below it.

Slow queries. A simple log detects what tests never see:

The comment marks a GDPR decision: the SQL template is logged, the values are not.

Two mechanisms from module 2 that now read as first-order optimisations.

fields (02-05): if Aroma Mobile's list only shows name, price and roast, asking for the whole object wastes bandwidth and serialisation.

Pagination (02-06): besides being mandatory by design (04-01), it is the most effective defence against degradation as things grow. And the cursor on /orders is not a whim: with offset=100000, the engine has to locate and discard 100,000 rows before returning 20. With a cursor, it jumps straight in by index.

Some operations do not fit inside a single request's cycle. Generating the PDF invoice for an order with twenty items, or the data export from the 04-02 exercise, take seconds.

Keeping the connection open is a bad idea: it exhausts the processes, clashes with the load balancer's timeouts and means a network failure forces the whole job to be repeated. The correct pattern:

The client polls the task resource:

And when it finishes:

Four design details:

• 202 means "accepted, not done yet", and it is different from 201 ("created"). The decision tree from 02-04 covered it.
• The task is a resource, with its URI, its representation and its _links. It is not a separate mechanism.
• Retry-After on the poll stops the client asking every 50 ms. It is the same mechanism as 04-04, applied to something that is not an error.
• 303 See Other on completion redirects to the final resource. And the catalogue's operation_in_progress code covers the case of asking for the invoice while it is still being generated.

For the internal back office, instead of polling we use SSE, which is already part of Aroma Store's architecture: the server pushes the status change when it happens.

Everything above is useless — or counterproductive — if it is applied blindly. The correct order is always: measure, find the real bottleneck, fix that, measure again.

Ten requests: nine at 20 ms and one at 2,000 ms.

The mean is an average of two different populations and describes neither. Percentiles are what you have to look at, and the p99 is the most important, because a page making 10 requests has roughly a 10% chance that at least one falls in the p99. Your p99 is the everyday experience of your most active users.

It is decided before optimising, and it becomes the criterion for knowing when to stop:

The login is deliberately the slowest: bcrypt with cost 12 takes ~100 ms on purpose (03-06). That is not a performance problem to be fixed, it is a defence working. Without the written budget, somebody will eventually "optimise" it by lowering bcrypt's cost.

Typical output:

How to read it without deceiving yourself:

• Look at the p99 (the 99% column), not the average.
• Always compare against a baseline taken before the change. An absolute number on its own says nothing.
• A single machine is not production: there is no real network latency, no CDN, no other instances and no real data.
• With little data, everything is fast. Test with a realistic volume: a 100-row table fits in memory and hides the absence of indexes.
• Watch CPU and memory during the test. If the CPU is at 100%, the bottleneck is yours; if it is at 20% and latency rises, the bottleneck is in the database or in a third party.

1. Measure and locate the genuinely slow endpoint, with production data.
2. Can the request be avoided? HTTP caching. It is the biggest possible gain.
3. Can the number of requests be reduced? expand (04-01).
4. Can the query be avoided? Server-side caching.
5. Can the query be made cheaper? Indexes, N+1, fields.
6. Can it be done later? 202 and asynchronous work.
7. Measure again and check against the budget.

And a final warning: caching adds complexity and a new class of bugs — stale data, incomplete invalidation, inconsistencies between levels. If an endpoint answers in 15 ms and is called ten times a day, caching it contributes nothing and adds one more way to fail.

Believing no-cache means "do not cache". It means "always revalidate". The one that prevents storing is no-store.

Forgetting private on personalised responses. A CDN can serve one user's orders to another. It is the most serious data leak in this lesson.

Caching error responses. A 429 cached for five minutes turns a one-minute block into five.

Using weak ETags for If-Match. They do not guarantee exact equality and the standard does not allow it. Express's automatic ETag is weak.

Returning a body on a 304. It is a protocol error; it also cancels out the saving.

Forgetting Vary. With content negotiation or CORS, it causes intermittent, impossible-to-reproduce crossed responses.

Caching stock. It causes overselling. Some data must be exact at all times.

Setting long TTLs in the browser. They cannot be purged. Short in the browser, long in the CDN with s-maxage.

Optimising without measuring. Most of the time is lost where nobody looks, and the work goes where things were already fast.

Tip: start with the catalogue. It is 80% of the traffic and the most cacheable. Solved well, it solves almost everything.

Tip: make the cache observable. Without hit and miss metrics you do not know whether it works. That is the subject of 04-07.

Tip: test the 304 explicitly. It is easy for the middleware to stop working in a refactor with nobody noticing: it only shows up on the bandwidth bill.

For each resource, decide the complete Cache-Control and whether you would emit an ETag. Justify each choice:

1. GET /v1/coffees?origin=Ethiopia — a filtered, public catalogue.
2. GET /v1/customers/cus_842/preferences — the authenticated user's preferences.
3. GET /v1/coffees/cof_001/image — an image whose name includes a hash.
4. POST /v1/sessions — it returns tokens.
5. GET /v1/orders/ord_5001 — the customer's own order, consulted frequently.
6. GET /v1/coffees/cof_001/reviews?sort=-createdAt — public reviews.

Implement conditional deletion of a review: DELETE /v1/reviews/{id} must require If-Match, return 204 if the version matches, 412 version_conflict if it does not, 428 precondition_required if the header is missing and 404 if it does not exist. Write the route, the service and an integration test for the four cases.

GET /v1/orders?limit=20&expand=items.coffee has a p50 of 45 ms and a p99 of 1,800 ms. The server's CPU sits at 25% during the load test. List at least four possible causes, ordered by likelihood, and say how you would verify and fix each one.

Solution 1

Solution 2

A design note: the 404 is checked before the If-Match, because it makes no sense to talk about the version of something that does not exist, and because answering 412 on a non-existent resource would leak information about its existence.

Solution 3

The CPU sitting at 25% rules out the Node process itself being the bottleneck. The distance between p50 and p99 (40×) points to something that happens only sometimes, not to a constant cost.

The procedure: first the slow query log from section 14, which in five minutes tells 1-2-3 (the database) apart from 5-6 (the process). Then measure against the budget (a p99 of 400 ms for writes; for this read it should be in the region of 150 ms) and stop when it is met, neither before nor after.

The "cacheable" constraint from 01-04 is now implementation. You know the four levels of caching and the rule that avoids the most serious leak — private on anything that depends on who is asking; you have mastered Cache-Control directive by directive, including that no-cache which does not mean "do not cache" and that stale-while-revalidate which eliminates the refresh wait; you have Aroma Store's policy resource by resource, with the catalogue cached and /v1/orders always revalidated. You have implemented conditional validation with a strong ETag — from a hash of the body or from the version field that already existed — and the complete 304 flow. And above all, the circle left open in 03-05 has been closed: If-Match and the 412 solve the lost update with standard HTTP semantics, they work with DELETE, intermediaries understand them and they reuse the very ETag the client received when reading; in exchange, the error catalogue grows with precondition_required (428), which has to be documented in openapi.yaml. In the project you have src/middleware/cache.js with cacheFor, conditionalEtag and requireIfMatch, src/services/cache.js with cache-aside and locking, src/services/cache-invalidation.js, and compression at position 7 with conditionalEtag at position 10 of src/app.js. Beyond caching: compression, keep-alive, indexes, the N+1 solved with a grouped query, fields, cursor pagination and the 202 with a task resource for the invoice. And, first of all even though it is told last, the latency budget, percentiles rather than the mean, and autocannon for measuring before touching anything.

Only one thing remains before closing the module, and it is what makes everything else possible: knowing what is going on. In 04-07, Observability: Logs, Metrics and Traces, we will finally replace the console.log at position 5 of src/app.js with structured logs using pino, with a child logger per request carrying the traceId we have been emitting since 03-02, the fields that must always be logged and the ones that must never be — passwords, tokens, personal data — with their automatic redaction. We will instrument Aroma Store with prom-client and the four golden signals, exposing a protected /metrics outside /v1, with the warning about the cardinality that blows up metrics systems. We will look at distributed tracing with traceparent and OpenTelemetry over a complete POST /v1/orders — validation, SQL, an inventory gRPC call and a webhook — the difference between liveness and readiness in /health, and how you alert on symptoms and SLOs rather than on CPU. And we will close the module with a tally of everything that has been hardened.