Concurrency, etags and caching

A site has more than one editor — a person in the admin, your integration, a scheduled job — and the default outcome when two of them save the same page is that the later write wins and nobody is told. The etag every resource carries is how you opt out of that.

Read it with the resource, send it back in If-Match, and a write that lost the race is refused instead of applied:

Code
etag=$(jq -r '.etag' <<<"$page")

curl_json "${auth[@]}" -X PATCH "$site/cms_pages/$page_id" \
  -H "If-Match: $etag" \
  -d '{"meta_description": "Created from the quickstart."}' >/dev/null

# That write minted a new etag, so the one above is now stale. Sending it again is what a
# second editor's Save looks like: 409 ABORTED, with the current resource in the body.
stale=$(curl_json "${auth[@]}" -X PATCH "$site/cms_pages/$page_id" \
  -H "If-Match: $etag" -d '{"title": "Hello again"}' || true)

jq '.error | {code, status, message}' <<<"$stale"

The refusal is a 409 with ABORTED and the current resource in the body, so a client has everything it needs to show the conflict — or to merge and retry — without a second request. Without If-Match the write is unconditional, which is fine for a field only you own and wrong for anything a person also edits.

The same value works on the way in: a GET with If-None-Match answers 304 when nothing changed, so a poller pays for headers rather than for a body.

14. Concurrency and etags

• A resource with concurrent editors MUST expose an etag, computed over its persisted state.
• A client MAY send If-Match: "<etag>". If the stored etag differs, the write fails ABORTED (409) and the response body carries the current resource.
• A resource MAY require If-Match on Update and Delete. It MUST document which.
• etag MAY also be echoed as an HTTP ETag header. The field is the contract; the header is a convenience.

16. Caching and conditional reads

• A GET with If-None-Match matching MUST return 304 with no body.
• Mutating responses are Cache-Control: no-store.