Search Results
  1. HTTP (Hypertext Transfer Protocol)
  1. Idempotent Requests in HTTP
    1. Safe methods
    2. PUT
    3. PUT to UUID
    4. Transaction/conditional headers

Idempotent Requests in HTTP

A request is considered idempotent when multiple identical requests have the same effect as one request. This is a desirable property of requests, because clients may re-try any requests that have failed due to a network error.

Idempotent methods are specified in RFC 9110 (HTTP Semantics) ยง9.2.2. Idempotent Methods

Safe methods

By definition, safe methods (which do not alter server state) are also idempotent:

  • GET
  • HEAD
  • OPTIONS
  • SEARCH
  • REPORT

PUT

The PUT method is considered idempotent because two requests in a row bring the server to the same state as just one request.

Using PUT does not, by itself, prevent lost updates: A situation where the second PUT request can overwrite changes made by another user since the first request was made. If you wish to protect against inadvertently overwriting other's changes, see Conditional Requests.

PUT to UUID

For most cases where POST is required (where an action is being carried out or a server must create a new resource), APIs may still use PUT to ensure the idempotency of the request. Normally you would make the request to an endpoint:

POST /query HTTP/1.1
Content-Type: application/json

{ "from": "Alice", "to": "Bob", "amount": 22.00 }

One technique to make this idempotent would be for the server to accept a client-generated UUID in the URI, for example /query/{uuid}. The user-agent picks a random value, and specifies If-None-Match: * as so:

PUT /query/2F0B31F4-38A2-4065-9EEF-71CC6AC2745F HTTP/1.1
If-None-Match: *
Content-Type: application/json

{ "from": "Alice", "to": "Bob", "amount": 22.00 }

The server may otherwise handle the request as a normal POST request, creating resources at other URIs:

HTTP/1.1 303 See Other
Location: /transactions/42

Subsequent GET requests will return the same response. The transaction resource may then be deleted by the user-agent, or automatically pruned by the server after a period of time.

This technique is mostly limited to APIs, since HTML does not support the PUT method, or a randomly generated form target (without scripting).

Transaction/conditional headers

Some vendors have introduced proprietary solutions, for example Stripe will recognize an Idempotency-Key header, and not perform a request if a previous request has been made with the same key. User-agents randomly generate a string for the header value, re-trying the request with the same header and payload until the server responds.