ETag header

As explained in The Design of Web APIs, Second Edition

An entity tag is an opaque HTTP validator identifying a particular version of a resource representation.

An ETag is an opaque HTTP validator identifying a particular version of a resource representation. Because content negotiation can produce different JSON and XML representations, each may have a different ETag. section 12.5.4 section 13.4.4

Use the ETag with conditional requests to protect updates and reduce response data:

• Return ETag: z567dff when reading a resource. section 12.5.4
• Send If-Match: z567dff on an update; return 412 Precondition Failed when the representation changed. section 12.5.4
• Send If-None-Match: z567dff when validating cached data; return 304 Not Modified if unchanged, or 200 OK with new data and ETag if modified. section 13.4.5

Preventing a stale account update

A consumer reads an account and receives ETag: z567dff. Before updating, it sends If-Match: z567dff. If another change occurred, the API rejects the request with 412, prompting the consumer to reread the account. section 12.5.4

Figure 12.5 By returning the resource data version in an Etag header on reading, we can condition updates with the If-Match header and ensure that data stays uncorrupted.

Trace how a returned ETag conditions a later update through If-Match. section 12.5.4

How The Design of Web APIs, Second Edition covers it

How deep it goes

Explains representation versioning, conditional headers, status outcomes, and implementation choices, but defers detailed RFC options.

Examples

Uses account reads, z567dff validators, conditional updates, cache validation, and 412 or 304 responses.

What it assumes

Assumes familiarity with HTTP requests, responses, resource representations, and basic caching concepts.

What you can do after

Apply HTTP conditional requests to prevent stale updates and retrieve cached data only when it changes.

How it connects

Connects HTTP caching, content negotiation, Cache-Control, If-Match, If-None-Match, Last-Modified, and 304 Not Modified.

liveBookmanning.com

Read The Design of Web APIs, Second Edition on liveBook Get the book at manning.com

Related concepts

• conditional requestused by · A conditional request is an HTTP request whose response depends on whether a supplied resource validator or other specified condition matches the server's representation.
• @Versionproduced by · @Version is the JPA annotation that identifies an entity property used for optimistic concurrency version checking.
• concurrency controlused by · Concurrency control coordinates simultaneous operations accessing shared state or resources to preserve correctness, consistency, and valid system behavior.
• content negotiationproduced by · Content negotiation is the HTTP process by which a client and server select a mutually supported representation format, language, or version.
• cachinguses · Caching is the practice of storing reusable data or computation results so later access can avoid repeating retrieval or computation.

This explainer was generated by Manning's knowledge graph from the text of The Design of Web APIs, Second Edition. The section links point to the parts of the book it draws on.