ETag and HTTP 304: Validate API Caches Correctly

Repeatedly downloading an unchanged product catalog wastes bandwidth and processing time. ETags let a client ask whether its stored representation is still usable. Where appropriate, the server can return HTTP 304 instead of transmitting the content again.

This article focuses on GET requests and cache behavior tests. The HTTP exchanges are illustrations, not benchmarks or universal API configurations.

1. An ETag is not an expiry time

RFC 9110 defines ETag as a validator for a representation. It need not be a hash or a database revision. A matching If-None-Match on GET produces 304 without a content body instead of 200 with the representation.

Separate how long a stored response may be reused from how it is subsequently validated. ETag addresses validation; cache directives govern freshness.

2. An illustrative exchange

GET /api/catalog HTTP/1.1
Host: api.example.com

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: private, no-cache
ETag: "catalog-v12"

{"items":[{"id":1,"name":"Keyboard"}]}

A later request can carry the received validator. Ordinary transport headers are omitted from these shortened examples.

GET /api/catalog HTTP/1.1
Host: api.example.com
If-None-Match: "catalog-v12"

HTTP/1.1 304 Not Modified
Cache-Control: private, no-cache
ETag: "catalog-v12"

The client reuses its stored body; 304 is not an empty JSON document. Changed data normally produces 200 with a new body and validator. Custom clients must manage stored responses rather than assuming every HTTP library includes browser-like caching.

3. Choose Cache-Control for the data

RFC 9111 distinguishes no-cache, requiring validation before reuse, from no-store, prohibiting storage. private restricts shared-cache storage; it does not encrypt data. max-age sets freshness rather than guaranteeing that origin data cannot change.

Do not choose a lifetime just because a number is popular online. Pricing and inventory need an explicit staleness tolerance and a decision about where transactional checks occur.

4. Make validators track the actual response

As an implementation exercise, list everything that can change the body: related records, language, filters and permissions. Use a revision only if it changes for every relevant update. A timestamp on one main table may miss changes elsewhere.

MDN's caching guide explains Vary for header-dependent representations. Nevertheless, Vary alone is not a user-isolation design. Explicitly test that user A cannot receive user B's body through any cache layer.

Strong and weak ETags have different comparison rules; W/ is meaningful. Prefer established conditional-request middleware to raw string comparison, which can mishandle tag lists or *. GET/304 behavior does not by itself solve write conflicts.

5. Measure the benefit and test the contract

A server that queries all records and serializes JSON before hashing it may save transfer bytes while retaining most response-construction cost. Measure transferred bytes, database time, CPU and latency separately. A high 304 ratio alone is not proof of a faster application.

• The first GET returns 200, the expected body and a valid validator.
• A current validator produces 304 without a content body.
• Changing relevant data makes subsequent validation deliver new content.
• Language, filter and identity changes cannot reuse the wrong representation.
• Revoked users remain denied even when presenting an old validator.
• Test through the real CDN or reverse proxy, not only the application directly.

Start with one low-risk endpoint and baseline measurements. ETags are useful when they reduce transfer while preserving data semantics; they are part of an HTTP contract, not a universal performance switch.