Restful Services Idempotent Law
Idempotent Law in Restful Service mean, the state of the server remains the same as after the first operation, irrespective of number times the operation is repeated. If a client calls an Restful Service, the resource state in the sever side will remain the same if the operation is idempotent. HTTP protocol has its on definition on which methods should be idempotent, and a Restful service must comply to that.
Let's take a real life example of Bank Account. Assume you are checking the balance of your account, you get to know the balance is certain amount. If you check the balance again, there is no change in the balance. Such operations are called idempotent operations. This example could be correlated with GET method of Restful Service. If you make multiple GET calls the resource state should not change and thus GET is idempotent.
Idempotency of HTTP Methods
Theoretically, a developer can end up developing non standard Restful services, if HTTP protocol is not respected. Rest API Details are communicated easily to others when it confirms to the industry standards. The table below shows the most commonly used HTTP methods and the Idempotent law it must confirm to.
HTTP Method | Idempotency | Reason |
|---|---|---|
GET | Idempotent | GET used for retrieving information, multiple retrieval does not change state of the resource. GET is Idempotent. |
POST | Not Idempotent | POST could be used to create a resource. for this reason resource id is not mentioned in URI. Calling a POST method multiple times will create resources each time. So, POST is not Idempotent |
DELETE | Idempotent | DELETE is used to delete a specific resource. Multiple attempt to DELETE yields the same result. DELETE is Idempotent. |
PUT | Idempotent | PUT is used for update or replace the resource mentioned in URI. For this reasons, a resource id is generally mentioned in the URI. Attempt to update the same resource with same values multiple times does not change the state of that resource. PUT is Idempotent. |
PATCH | Not Idempotent | PATCH is used to update a portion of the resource. PATCH is not Idempotent |
Idempotent Vs Safe Methods
Idempotent methods are not always safe, but all the safe methods are Idempotent. Safe methods are read only methods that do not change the server state. Idempotent method call could change the state, but the subsequent calls will give the same result. The highlight here is subsequent call. Thus DELETE and PUT methods are not safe, even though they are classified as Idempotent.
Why POST Is Not Idempotent?
POST is called without passing an object Id for the purpose of creation. For the same reason POST results in creation of a new object assign its own Id. Every consequent POST calls will create a new object and assign a new Id, adding the object to the collection. Thus POST is not Idempotent.
Practical Considerations
Developer community usually gets question on situations were a given HTTP method could be Idempotent or not. For example, Patch is for update, so subsequent update should give you the same result. Most of the time this is the case. But there are situations you decide to update a different part of the resource, or subsequent update is based on the previous update. Thus it becomes non Idempotent.
Another situation is when you do NOT give id as part of PUT. Here the API can choose to create a new resource. In practice, this approach may be avoided. Keep it simple - use POST to create and PUT to update.
There are also practical situations when a subsequent Idempotent call might have to change the state. Consider, you are implementing a Stack data structure kind of service. If you use DELETE ( in the place of classical Stack method of pop() ), you will be deleting from the last - popping out in a FILO model. Each DELETE will change the state in the server until the stack is empty. You should not use DELETE here, instead should use POST method here to achieve the functionality, as POST is not Idempotent.
When in doubt, make HTTP recommendations are the guideline. This will not only make your API Rest compliant, but also easy communication with the clients as they will able to develop based on HTTP standards.