Search Results
  1. HTTP (Hypertext Transfer Protocol)
  1. HTTP Headers
  1. If-Match
    1. Writing requests (clients)
    2. Reading requests (intermediaries)
    3. Reading requests (origin servers)
    4. Overview table
    5. Syntax
    6. Matching
      1. Strong comparison
      2. Weak comparison

If-Match

The "If-Match" header field makes a request conditional on a target resource (on the cache or origin) being the specified ETag. ETags are compared using the strong validation function (the ETags must match exactly). This form is typically used when operating on a resource, e.g. saving a new version, to prevent lost updates. If the request fails, the server will respond with 412 (Precondition Failed); otherwise, the request will proceed. The equivelant header for Last-Modified is If-Unmodified-Since.

An If-Match: * form is also defined, which makes the request conditional on the resource existing. This only makes sense for requests that do not return 404 Not Found, e.g. PUT or PATCH.

Writing requests (clients)

A client typically uses If-Match header when making a change to a resource, and must not overwrite modifications made by a third party since the client's last request. Use this header with the ETag of the previous known document version.

If the client is creating a new resource and must not overwrite any existing resource, use If-None-Match with * instead.

Refer to the appropriate status code for handling the response. If this condition failed, this status code will be 412 Precondition Failed.

Reading requests (intermediaries)

Caches and other intermediate nodes can typically ignore this header, as it is not used in caching.

Reading requests (origin servers)

Conditional headers are evaluated after other normal checks (after method, lookup, and authentication), but before any changes are made. For performance and error messages, If-Match may be evaluated first, then If-Inmodified-Since, If-None-Match, If-Modified-Since, and If-Range.

If the requested action would have no effect on the current state of the resource, the server may choose to return success, even if there would otherwise be a comparison mismatch. For example, when handling a PUT request identical to the current document, or a PATCH request that is an effective no-op, the server may choose to respond with 200 OK instead of 412 Precondition Failed.

If the value is * and the resource does not exist, return 412 (Precondition Failed).

If the value is the ETag form, use the strong comparison function to compare each ETag to the resource's current ETag. If none of the comparisons match, return 412 (Precondition Failed).

If the request is missing a precondition header and the server requires one to protect against lost updates, see 428 (Precondition Required).

Overview table

Name
If-Match
Description
makes filling a request conditional on the resource having one of the specified ETags
Direction
Request
Specification
RFC 7232: HTTP/1.1 Conditional Requests ยง3.1. If-Match

Syntax

If-Match = "*" / 1#entity-tag

Matching

ETags can be matched with one of two algorithms:

Strong comparison

With a strong comparison, the ETags must match, and neither can be a weak ETag.

Weak comparison

With a weak comparison, the ETags must match, and may have a weak flag, which is otherwise ignored.