[ADP-131] If-Match

reviewing phase 1

Explain why not use weak Etag.

Overview

The If-Match header is a conditional request header used in HTTP to make a request conditional based on the current ETag value of a resource. It is primarily used to prevent the "lost update" problem in concurrent modifications and to ensure data integrity in PUT, PATCH, or DELETE operations.

Purpose

The main purposes of the If-Match header are:

To prevent simultaneous updates from overwriting each other (the "lost update" problem).
To ensure that a resource hasn't been modified since it was last retrieved.
To implement optimistic concurrency control in RESTful APIs.

Guidance

Servers MUST support the If-Match header for PUT, PATCH, and DELETE operations to prevent the "lost update" problem.
Clients SHOULD include the If-Match header in requests that modify or delete resources to ensure data integrity.
Servers MUST respond with a 412 (Precondition Failed) status code if the ETag doesn't match the provided If-Match value.
Implementations SHOULD use strong ETags with If-Match for better precision.
Servers MUST include the current ETag in GET responses to allow clients to use it in subsequent conditional requests.
API developers SHOULD implement proper ETag generation and handling on the server side.
Error responses for 412 status codes SHOULD include clear error messages to help clients understand the failure reason.
Clients MUST NOT use weak ETags in If-Match headers, as per RFC 7232.
Servers SHOULD support multiple ETag values in a single If-Match header.
API documentation MUST clearly explain the behavior and usage of If-Match in the API's context.

Usage

The If-Match header can be used in the following ways:

With a specific ETag value:
http
```
If-Match: "123456789"
```
With multiple ETag values:
http
```
If-Match: "123456789", "abcdefghijk"
```
With a wildcard value (matches any ETag):
http
```
If-Match: *
```

Behavior

If the ETag of the resource matches the value in the If-Match header, the server processes the request normally.
If the ETag doesn't match, the server should respond with a 412 (Precondition Failed) status code.
If the resource doesn't exist and the If-Match header uses a wildcard (*), the server should respond with a 412 (Precondition Failed) status code.

Best Practices

Always use If-Match in conjunction with ETags for PUT, PATCH, and DELETE operations to prevent lost updates.
Implement proper ETag generation and handling on the server side.
Use strong ETags instead of weak ETags with If-Match for better precision.
Include the current ETag in GET responses to allow clients to use it in subsequent conditional requests.
Handle If-Match headers properly in your API implementation to ensure data integrity.

Example

http

PUT /users/123 HTTP/1.1
Host: api.example.com
If-Match: "abc123"
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com"
}

In this example, the PUT request will only be processed if the current ETag of the resource matches "abc123".

[ADP-131] If-Match ​

Overview ​

Purpose ​

Guidance ​

Usage ​

Behavior ​

Best Practices ​

Example ​

Related ADPs ​

References ​