Conditional GET as API Design

## What the two validators are A **validator** is a token the server attaches to a representation so a later request can ask "has this changed?". HTTP defines two. - `ETag: "7c9e"` — an **entity tag**: an opaque string chosen by the server. Clients never interpret it, only echo it back in `If-None-Match`. Because it is opaque, you can derive it from anything: a database row version, a rowversion/xmin column, a monotonic change sequence, or a hash of the serialized body. - `Last-Modified: Tue, 12 Aug 2026 09:14:02 GMT` — the time the representation last changed, echoed back in `If-Modified-Since`. ## Choosing per resource **Resolution.** `Last-Modified` has one-second granularity, and HTTP dates cannot express anything finer. If a resource can change twice within the same second — counters, order status, anything edited by machines — a client that fetched mid-second can be told "not modified" when it was. An ETag has no such limit. This alone pushes most write-heavy API resources to ETags. **Cost of computing it.** The validator only pays off if it is far cheaper than the representation. A row `version` or `updated_at` column read by primary key is ideal: the handler can answer 304 after one indexed lookup. Hashing the serialized body is the opposite — you did all the work and saved only egress. If hashing is your only option, at least cache the hash next to the data. **Does a modification time exist and mean anything?** For a stored document, `updated_at` is natural. For a computed or aggregated representation (a dashboard rollup, a search result page) there is no honest modification time, and inventing one is worse than emitting an ETag over the inputs' version vector. **Collections are the hard case.** A list resource changes when any member changes, when a member is added, and when one is deleted. `max(updated_at)` alone misses deletions, so a common recipe is `max(updated_at)` combined with a row count, or better, a per-tenant change sequence bumped on every mutation. The validator must also cover the query parameters that shaped the response — page, sort, filter — or two different pages will share a validator. **Heuristic freshness.** RFC 9111 lets a cache guess a freshness lifetime when you send no explicit one, typically from the `Last-Modified` age. That is a reason to include `Last-Modified` on slow-changing public resources — but a better practice is to send an explicit freshness lifetime rather than rely on a heuristic you do not control. **Both.** Sending both is legal and common. Clients then send both `If-None-Match` and `If-Modified-Since`; a server that supports the entity tag evaluates that one and ignores the date. Do it when both are free; do not build a second validator pipeline just for completeness. **Neither.** Legitimate when the representation is different on every request by design (a live quote, a randomized feed), when it is smaller than the headers it would need, or when the resource is write-only or one-shot. Being explicit about "no validator" is a design decision, not an omission — document it so client teams do not build revalidation logic that never hits. ## Contract consequences beyond caching Entity tags are also the raw material for optimistic concurrency: a client that received `ETag: "7c9e"` can send `If-Match: "7c9e"` on its update so the server rejects the write if someone else changed the resource meanwhile. If you plan to offer that, you need ETags on exactly the resources clients mutate — and they must be strong ETags, since precondition evaluation on writes uses strong comparison. Deciding validators resource-by-resource is therefore not only a caching decision; it decides which resources can support safe concurrent editing. ## Stability is the whole game Whatever source you pick, the validator must be stable while nothing meaningful changed. Server timestamps in the body, request ids echoed into the payload, non-deterministic map ordering, and per-request pagination cursors all cause validator churn and turn revalidation into pure overhead — a round trip that always returns 200. Determinism in serialization is a prerequisite for conditional GET to be worth offering.