ETags and If-Match: Prevent Lost Updates in Your API
Two editors can overwrite each other even when both saves succeed. Use ETags, If-Match and an atomic version guard, then give stale edits a recovery path.
DM
Imagine two teammates editing the same delivery rule in your SaaS dashboard. Both open version 12. One changes the destination; the other changes the label. If each saves the entire old form, the second save can quietly restore the old destination. This is a hypothetical example of a lost update.
Give the read response a strong ETag, require the client to send it back in If-Match, and make the version check and database write one atomic operation. When the version has changed, preserve the unsaved edit and let the person reconcile it with the current record. Automatically fetching a newer tag and resending the old form would hide the conflict.
Agree on what the version represents
HTTP Semantics, section 13.1.1 defines If-Match and requires strong comparison. A weak tag such as W/"rule-12" cannot satisfy that comparison. The wildcard If-Match: * checks that a representation exists; it does not say which version the person edited.
For this example, assume one JSON representation per rule and a revision counter that changes whenever any represented field changes. The API emits a quoted opaque tag derived from that revision. This is a proposed contract, not a universal recipe: content negotiation, compression, derived fields and additional writers can invalidate a simplistic counter-to-ETag mapping. Design the validator for the actual representation you serve.
GET /rules/42 HTTP/1.1
Host: api.example.com
HTTP/1.1 200 OK
Content-Type: application/json
ETag: "rule-42-v12"
{"destination":"warehouse-a","label":"Morning delivery"}The response above is illustrative. The client should retain the body and its ETag together as the edit's starting point. Keep the person's proposed changes separately. Those three pieces—the starting record, the current record and the proposed edit—make a useful conflict screen possible.
Put the guard in the write
An application can compare two versions correctly and still lose an update if another request writes between that comparison and an unconditional save. Microsoft's API implementation guidance recommends enforcing the comparison and mutation atomically in the data store.
Here is a deliberately narrow PostgreSQL example. Assume delivery_rules has a primary key of (tenant_id, id), a non-null revision bigint, and the two text fields below. The handler has already authenticated the caller, authorized this rule, validated the request and decoded one valid version tag. Bind parameters through the database driver; do not build SQL from header text.
UPDATE delivery_rules
SET destination = $1,
label = $2,
revision = revision + 1
WHERE tenant_id = $3
AND id = $4
AND revision = $5
RETURNING revision;For this single-row design, a returned row means the guarded statement changed that row; acknowledge success only after a confirmed transaction commit. No returned row is not a successful save. It can mean a stale revision or an absent row in this authorized scope. Resolve those cases according to your API's documented policy without revealing another tenant's records. See PostgreSQL's UPDATE reference for RETURNING and affected-row behavior.
At PostgreSQL's default Read Committed isolation level, a competing update can wait for the first updater and then re-evaluate its WHERE condition against the updated row. The transaction isolation documentation explains that behavior. With both callers expecting revision 12, a committed first update advances the revision and prevents the second statement from matching it.
That reasoning depends on every relevant writer advancing the revision. An admin script that changes the destination without changing the counter breaks the contract. Inventory background jobs, imports and repair scripts as well as dashboard saves. For a resource assembled from several tables, define a transaction and validator covering the whole resource; this one-table statement is insufficient. Do not reuse a validator when a deleted rule is recreated at the same URL; include a new resource incarnation in the version identity.
Give the rejected edit a recovery path
PUT /rules/42 HTTP/1.1
Host: api.example.com
Content-Type: application/json
If-Match: "rule-42-v12"
{"destination":"warehouse-a","label":"Early delivery"}If the teammate's destination change has already committed, this hypothetical request carries an old tag. Reject the stale write. Keep the local label edit, retrieve the current rule and show what changed before offering a new submission. A field-level merge may be straightforward here; two competing destination changes need an explicit choice.
Use 412 Precondition Failed for a failed version precondition. If your endpoint requires a condition and the client omits it, RFC 6585, section 3 provides 428 Precondition Required. Its response should explain how to submit a conditional request, and a cache must not store a 428 response. Authentication, authorization and ordinary request errors still need their own handling.
After a successful save, retrieve the stored representation and its current validator before starting another edit. That keeps this example clear when the server normalizes fields. HTTP places specific restrictions on sending validators in successful PUT responses when the submitted representation was transformed; follow section 9.3.4 when defining your response.
A connection failure after submission leaves the outcome uncertain. Re-read and reconcile rather than replacing the old tag silently. Version guards also differ from operation deduplication: if an update triggers a payment or external job, that side effect needs its own recovery design. Krova's webhook retry guide explains the separate operation-identity problem.
Try two editors before relying on the guard
Use a disposable rule and test credentials in staging. This is a proposed acceptance exercise, not a report of tests we ran.
- Read the same rule twice and retain both original tags. Save a destination change through the first client, then submit the second client's label change using its old tag. Expect a conflict and verify the first destination survives.
- Repeat with overlapping requests. Check persisted state and revision, not just HTTP responses. For two valid, different writes against the same revision, only one should commit.
- Submit without If-Match and with a stale or weak tag. Check the documented rejection behavior. Exercise malformed headers and supported tag-list or wildcard syntax through an HTTP-aware parser.
- Change the rule through a background writer. Verify the old dashboard tag becomes stale. Then simulate a lost success response and confirm the client preserves the edit while reconciling the actual stored state.
Start with one route and write down its validator scope, stale-write response and conflict-screen behavior. Expand only after all writers follow the same version rule. A version counter does not replace permissions, database backups or recovery for external effects.
A Krova Cube is a self-managed Linux microVM with root access, suitable for an API and staging database you operate. Cube provides the compute environment; your application owns the concurrency contract, database maintenance and backup plan.
Rehearse concurrent saves on a Cube
Build a disposable API environment and verify stale writes, background updates and uncertain responses before connecting production records.
Creation context: AI-assisted guidance based on the linked primary documentation, checked on 15 November 2026. The delivery-rule scenario, SQL and acceptance exercise are illustrative and were not executed. No personal testing by the bylined author is claimed. The cover is an AI-generated conceptual illustration.




