← Back

ETag Concurrency: Stop Silent Lost Updates

Use ETags and If-Match to reject stale writes before they overwrite another edit. Connect HTTP preconditions to atomic database updates and conflict recovery.

ETag optimistic concurrency protects a familiar workflow: two people open the same record, both edit it, and the second save silently overwrites the first. The goal is not to prevent simultaneous editing. It is to make a conflicting save visible before data disappears.

For a hypothetical project settings page, I would attach a revision to the representation the user loaded. The save request must present that revision. The server updates the record only if it is still current, and the interface offers a useful recovery path when it is not.

Carry the version through the HTTP contract

HTTP If-Match expresses a precondition using an entity tag. It uses strong comparison, so a weak ETag is not suitable for this comparison. When the condition fails, the server normally responds with 412 Precondition Failed. See the If-Match reference.

An illustrative exchange is:

GET /projects/42/settings

HTTP/1.1 200 OK
ETag: "settings-17"
Content-Type: application/json

{"name":"Workshop","timezone":"Europe/Berlin"}

The subsequent update includes:

PUT /projects/42/settings
If-Match: "settings-17"
Content-Type: application/json

{"name":"Design Workshop","timezone":"Europe/Berlin"}

These are shortened protocol sketches, not complete wire captures. The server must still authenticate the caller, authorize the operation, validate the payload, and implement the update atomically.

Make the database enforce the comparison

Checking the revision in one query and updating unconditionally in another leaves a race. Another writer can modify the row between those two operations. In my proposed schema, the update predicate includes both identity and the expected revision:

UPDATE project_settings
SET name = $1,
    timezone = $2,
    revision = revision + 1
WHERE project_id = $3
  AND tenant_id = $4
  AND revision = $5
RETURNING revision;

The example assumes the server has independently authorized the tenant and parsed a valid expected revision. An affected-row count of zero requires deliberate handling: the record may be missing, inaccessible, or changed. Avoid exposing another tenant's resource existence while resolving those cases.

Return the new representation and validator after a successful update. If the response itself is lost, the client may not know whether the save succeeded. A subsequent read can help reconcile the current state, but do not automatically reinterpret a failed precondition as proof that the earlier write failed.

Make the validator describe the representation

RFC 9110 defines entity tags, strong validators, and conditional request semantics. A strong validator must change when representation data changes in the relevant way; consult HTTP Semantics when designing that mapping.

For the proposed settings endpoint, a numeric revision works only if every change to the represented settings advances it. A background job, administrative update, or migration that edits the same fields without advancing the revision breaks the contract.

Also account for representation variants. If the response includes derived fields or localized text, one underlying row revision may not fully describe the emitted representation. I would keep the editable settings representation small and stable, or explicitly include the additional version dependencies.

Do not treat an ETag as authorization. A caller who learns the current validator still needs permission to read or modify the project. The revision checks freshness, not identity or ownership.

Design the conflict screen before shipping the endpoint

Imagine Alice changes the project name while Ben changes its timezone. Ben's old revision is rejected. The interface should preserve Ben's unsaved value and explain that another update occurred. Discarding his form is technically safe but unnecessarily hostile.

For this product, I would show the freshly loaded settings next to the user's pending changes and let the user decide whether to apply them. Automatic field merging is possible only after defining conflict semantics. Two different fields may still be related by business rules.

Avoid a “force save” button that simply removes the precondition. If the product supports deliberate overwrite, make it an explicit privileged action with clear consequences and an audit record. Otherwise the concurrency protection disappears precisely when it matters.

Test two writers with a barrier

A deterministic fixture is more convincing than rapidly clicking two browser windows:

  1. Load revision 17 for clients A and B.
  2. Hold both clients before saving.
  3. Let A update successfully and receive revision 18.
  4. Submit B with revision 17.
  5. Verify B receives a conflict and A's data remains intact.
  6. Reload, reconcile, and save B's chosen changes using revision 18.

Add tests for missing preconditions according to your API's documented policy, malformed validators, unauthorized tenants, and writes from background code. The strongest endpoint test cannot compensate for another write path that ignores the version model.

The HTTP caching guide covers representation freshness for reads. The migration compatibility guide explains why every writer, including older application versions, must preserve the revision contract used for updates.

I would consider optimistic concurrency complete only when both sides work: stale writes are rejected atomically, and a user can recover without losing their own draft. The header is the beginning of that contract.