1. Idempotent APIs
In the context of REST APIs, when making multiple identical requests has the same effect as making a single request – then that REST API is called idempotent.
When we design the REST APIs, we must realize that the API consumers can make mistakes. Consumers can write the client code in such a way that there can be duplicate requests coming to the API.
These duplicate requests may be unintentional as well as intentional sometimes (e.g. due to timeout or network issues).
We have to make our APIs fault-tolerant in such a way that the duplicate requests do not leave the system unstable.
An idempotent HTTP method is a method that can be invoked many times without the different outcomes. It should not matter if the method has been called only once, or ten times over. The result should always be the same.
Idempotency essentially means that the result of a successfully performed request is independent of the number of times it is executed.
For example, in arithmetic, adding zero to a number is an idempotent operation.
2. Idempotency with HTTP Methods
If we follow the REST principles in designing our APIs, we will have automatically idempotent REST APIs for GET, PUT, DELETE, HEAD, OPTIONS, and TRACE methods. Only
POST APIs will not be idempotent.
POSTis NOT idempotent.
Let’s analyze how the above HTTP methods end up being idempotent – and why POST is not.
2.1. HTTP POST
Generally – not necessarily –
POST APIs are used to create a new resource on the server.
So when we invoke the same POST request N times, we will have N new resources on the server. So, POST is not idempotent.
2.2. HTTP GET, HEAD, OPTIONS and TRACE
TRACE methods NEVER change the resource state on the server. They are purely for retrieving the resource representation or metadata at that point in time.
So invoking multiple requests will not have any write operation on the server, so GET, HEAD, OPTIONS, and TRACE are idempotent.
2.3. HTTP PUT
Generally – not necessarily –
PUT APIs are used to update the resource state. If you invoke a
PUT API N times, the very first request will update the resource; the other N-1 requests will just overwrite the same resource state again and again – effectively not changing anything.
Hence, PUT is idempotent.
2.4 HTTP DELETE
2.4.1. Delete with the resource identifier
When you invoke N similar
DELETE requests, the first request will delete the resource and the response will be
200 (OK) or
204 (No Content).
Other N-1 requests will return 404 (Not Found).
Clearly, the response is different from the first request, but there is no change of state for any resource on the server-side because the original resource is already deleted.
So, DELETE is idempotent.
2.4.1. Delete without the resource identifier
Please keep in mind if some systems may have DELETE APIs like this:
In the above case, calling operation N times will delete N resources – hence
DELETE is not idempotent in this case. In this case, a good suggestion might be to change the above API to POST – because POST is not idempotent.
Now, this is closer to HTTP spec – hence more REST compliant.