ETag

Conditional Requests & Concurrency IANA permanent response reached by regulation 4 spellings

An ETag is an opaque version token for a representation. Its original job was caching — pair it with If-None-Match and a client can revalidate without re-downloading. Its more valuable job in an API is concurrency: pair it with If-Match on a write and the server can reject an update computed against a version that has since moved.

That second use is what put a caching header inside a certification programme. FHIR R4 uses ETag and If-Match for optimistic locking on versioned resources, and the ONC Health IT Certification criteria reference the FHIR behaviour — so a general-purpose HTTP header ends up load-bearing in US health IT conformance.

One hundred and twenty-five providers declare it. If-None-Match appears in 76 and If-Match in 76, which is the more telling number: it means most of the providers who emit version tokens never accept them back.

The registry

Listed in the IANA HTTP Field Name Registry as a permanent entry. Defined in RFC 9110, Section 8.8.3: HTTP Semantics.

In the catalog

Declared by 125 providers across 7,568 published specification files in the API Evangelist catalog, where it appears as a response header — sent by the server.

It is spelled 4 different ways across those contracts — ETag, etag, Etag, eTag. HTTP field names are case-insensitive (RFC 9110, §5.1), so every one of these is the same header. They are not the same string, which is why generated clients disagree about it.

Reached by regulation

This header is mandated: the law, or a technical standard the law makes binding, names it directly. It is observable at the edge: an unauthenticated request is enough to see whether a provider sends it.

Using it

Emit an ETag on any resource that can be updated, and accept If-Match on the corresponding write, returning 412 Precondition Failed on a mismatch. Emitting an ETag you will not accept back is decoration.

Use a strong ETag unless you have a specific reason not to, and never derive it from a timestamp with second granularity — two writes in the same second will collide, which is exactly the case the mechanism exists to catch.