Getty Images
Idempotent HTTP methods and REST
The Hypertext Transport Protocol requires all HTTP verbs to identify as idempotent or not. But what is an idempotent method, and how does idempotence apply to RESTful API design?
The Hypertext Transport Protocol requires all HTTP methods to declare whether they are idempotent or not.
With an idempotent HTTP method, multiple invocations always leave the data on the server in the same state. A RESTful delete of a newsletter subscription is an idempotent operation, because the result of multiple requests is always the same thing: a deleted subscription.
For an HTTP method to be idempotent in REST, no matter how many times that method is invoked, the data on the server always remains in the same state.
List of idempotent HTTP methods
The following idempotent HTTP methods are most commonly used:
- PUT.
- DELETE.
- GET.
Lesser used idempotent HTTP verbs include the following:
- HEAD.
- OPTIONS.
- TRACE.
The HTTP verbs GET, HEAD, OPTIONS and TRACE are all categorized as safe operations that should never update server-side resources. A safe operation is idempotent by definition.
Non-idempotent HTTP verbs
The three commonly used HTTP verbs that are not idempotent are POST, PATCH and CONNECT.
POST is used to process data or create resources when a resource URL is unknown.
PATCH is used to update a resource based on a set of changes defined in its payload.
CONNECT is rarely used in RESTful APIs. Instead, it simply uses HTTP to connect to a proxy server to create a VPN.
Examples of idempotence
The concept of idempotence in REST, and how idempotent methods behave at runtime, is best explained through examples.
As stated earlier, one can invoke idempotent operations multiple times but the server always remains in the same, consistent state. The following examples illustrate this concept:
- I instruct the server to DELETE my subscription 100 times. No matter how many times the operation happens, the result is that my subscription is deleted.
- I tell the server to PUT a flight-status resource on the server that indicates plane AC123 is on-time. Invoking this operation multiple times always results in an on-time status.
- I assign the server to PUT a change to my address. Multiple invocations do not create multiple addresses. Instead, each invocation results in the same address saved.
Idempotent HTTP methods
| HTTP method | Safe | Idempotent |
| GET | Yes | Yes |
| POST | No | No |
| PUT | No | Yes |
| PATCH | No | No |
| DELETE | No | Yes |
| TRACE | Yes | Yes |
| HEAD | Yes | Yes |
| OPTIONS | Yes | Yes |
| CONNECT | No | No |
| PRI | Yes | Yes |
Non-idempotent examples
An operation is not idempotent if it leaves resources on the server in a different state every time it is invoked. Here are some examples of non-idempotent RESTful operations:
- Raise everyone's salary by 10%.
- Append another entry to the bottom of a log file.
- Increase the number of event attendees by 100.
If you increase everyone's salary by 10% seven times, you'll nearly double everyone's salary. Each time the operation takes place, the server-side resource is assigned a new value. Thus, the operation is definitely not idempotent.
Idempotent RESTful API design
One of the challenges with the development of idempotent RESTful APIs is that there is no mechanism on the server to enforce an operation's safety or idempotence.
A poorly implemented GET operation could be both unsafe and non-idempotent. It is up to the API architects and software developers to understand how to properly design RESTful APIs that respect the concept of idempotence and safety.
