[ADP-133] If-None-Match

Overview

The If-None-Match header is a conditional HTTP request header that allows clients to make requests conditional on the ETag of the resource. It is primarily used for cache validation and to prevent unnecessary data transfer.

Purpose

The main purposes of the If-None-Match header are:

1. To validate cached resources
2. To prevent unnecessary data transfer
3. To implement optimistic concurrency control

Guidance

• API implementers MUST support the If-None-Match header for GET and HEAD requests to enable efficient caching.
• Servers SHOULD generate and include ETags in responses for cacheable resources.
• Clients SHOULD include the If-None-Match header in requests when they have a cached copy of the resource.
• When implementing PUT, POST, or PATCH operations, servers SHOULD honor the If-None-Match header to prevent unintended overwrites.
• API documentation SHOULD clearly explain how If-None-Match is used in the API, including any resource-specific behaviors.

Usage

Syntax

If-None-Match: <etag_value>
If-None-Match: <etag_value>, <etag_value>, ...
If-None-Match: *

• <etag_value>: The ETag value of the resource
• *: Matches any existing entity

Behavior

• For GET and HEAD requests:

  • If the ETag of the resource matches any of the provided ETags, the server should respond with a 304 (Not Modified) status.
  • If the ETag doesn't match, the server should respond with a 200 OK and the full resource.

• For PUT, POST, and PATCH requests:

  • If the ETag matches, the server should respond with a 412 (Precondition Failed) status.
  • If the ETag doesn't match, the server should process the request normally.

Example

Request

GET /users/123 HTTP/1.1
Host: example.com
If-None-Match: "abc123", "def456"

Response (Not Modified)

HTTP/1.1 304 Not Modified
ETag: "abc123"

Response (Modified)

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

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

Related ADPs

• ADP-128 ETag
• ADP-132 If-Match

References

• RFC 9110: If-None-Match
• MDN Web Docs: If-None-Match

Changelog

• 2024.09.24 Remove unwanted /api path in the samples