Idempotent

Concepts

Overview

Idempotent means that making the same request once or many times leaves the server in the same final state.

GET, PUT, DELETE, and HEAD are defined as idempotent; POST generally is not.

Details

The key misconception is equating 'idempotent' with 'safe'. Idempotent means 'repeating it yields the same resulting state,' not 'it changes nothing.' For example, `DELETE /users/42` does change state (it removes the user), but calling it twice still leaves '42 does not exist,' so it's idempotent. `PUT /users/42` that overwrites the whole resource to a specific value ends in the same value no matter how many times you send it, so it's idempotent too. `POST /users`, by contrast, creates a new user each call and is not idempotent.

Idempotency is the basis for reliable retries: if a network timeout hides the response, an idempotent request can be safely re-sent. To safely retry a non-idempotent POST (payment, order), you use an 'Idempotency-Key' header so the server can detect duplicates. (Note: in practice PATCH may or may not be idempotent, depending on the implementation.)

Related types