If-Match

Description

If-Match implements optimistic concurrency control in HTTP without pessimistic locking. Race condition timeline (why If-Match exists): T=0 Client A: GET /articles/42 → ETag: "v7" T=0 Client B: GET /articles/42 → ETag: "v7" T=1 Client B: PUT /articles/42 If-Match: "v7" → 200 OK, ETag now "v8" T=2 Client A: PUT /articles/42 If-Match: "v7" → 412 Precondition Failed Client A must re-fetch (new ETag "v8"), merge, and retry with If-Match: "v8". Without If-Match, Client A's write at T=2 would silently overwrite Client B's work. Workflow: 1. Read resource: GET /resource → server returns ETag in response header 2. Edit locally 3. Write with guard: PUT/PATCH/DELETE + If-Match: "<etag>" 4a. ETag matches → server applies change → 200/204, new ETag 4b. ETag changed → 412 Precondition Failed → re-fetch, merge, retry If-Match: * semantics: Matches any current representation – but only if the resource EXISTS. Does NOT match if the resource does not exist (returns 412). To create-only-if-absent, use If-None-Match: * (412 if resource already exists). Strong vs weak ETags: If-Match requires STRONG ETags. Weak ETags (W/"abc") MUST NOT be used with If-Match for unsafe methods (PUT, PATCH, DELETE) per RFC 9110 §13.1.1. A server receiving a weak ETag in If-Match for an unsafe method SHOULD return 412. Semantic relationships: ETag ←generated by server, identifies resource state ↓ sent by client in If-Match → unsafe request (PUT/PATCH/DELETE) → success or 412 If-None-Match → safe request (GET/HEAD) → 304 or full response ↓ 412 Precondition Failed → client re-fetches with GET, gets new ETag ↓ Client merges and retries with new ETag → 200/204

Directives

Examples

GET /api/articles/42 HTTP/1.1
Host: api.example.com

HTTP/1.1 200 OK
ETag: "v7-abc123"
Content-Type: application/json

{"title": "Original Title", "body": "..."}

---

PUT /api/articles/42 HTTP/1.1
Host: api.example.com
If-Match: "v7-abc123"
Content-Type: application/json

{"title": "Updated Title", "body": "..."}

PUT /api/articles/42 HTTP/1.1
If-Match: "v7-abc123"
Content-Type: application/json

{"title": "My Update"}

HTTP/1.1 412 Precondition Failed
ETag: "v8-xyz789"
Content-Type: application/json

{"error": "precondition_failed", "current_etag": "v8-xyz789"}

DELETE /api/sessions/sess_abc HTTP/1.1
If-Match: "active-v1"

HTTP/1.1 204 No Content

# Second attempt after deletion:
DELETE /api/sessions/sess_abc HTTP/1.1
If-Match: "active-v1"

HTTP/1.1 412 Precondition Failed

PUT /api/config/limits HTTP/1.1
If-Match: *
Content-Type: application/json

{"max_uploads": 100}

# Returns 412 if /api/config/limits does not exist
# Use If-None-Match: * to create only if NOT exists

Related