An ETag is a string the server attaches to a response that identifies that particular version of that particular representation. It is opaque: it might be a hash, a version number or a timestamp, and a client must never try to interpret it — only send it back.
On a read, the client returns the ETag in If-None-Match; if it still matches, the server answers 304 Not Modified with no body and the client uses its cached copy. On a write, the client sends it in If-Match; if it no longer matches, the server answers 412 Precondition Failed and the write is refused. Same value, two headers, two entirely different jobs — one saves bandwidth, the other prevents a lost update.
That an ETag mismatch means something went wrong. A 412 is the mechanism working: it means somebody else changed the resource since you read it, and your write would have silently overwritten theirs. The correct response is to re-read, reconcile, and try again with the new ETag — not to retry with the old one, which will fail identically forever.
The Football and FIBA standings endpoints answer conditional reads with 304. The character, hero and movie writes accept If-Match and produce a real 412 when the version is stale.
All glossary terms · Testing techniques · All 39 mock REST APIs