Idempotency is the ability for an operation to be carried out multiple times without changing the state of the system.
With this definition we can say regularly used methods like the PUT and GET are idempotent since regardless of what is sent in the request or how many times you make the request the outcome remains the same. Lets take the GET method as an example
GET https://api-resource/api/v1/getData
No matter how many times the endpoint is called, it will always result in the same outcome, the system remains unchanged.
Now lets answer the question why is the DELETE method idempotent? Deleting the item from the first call removes the item from the system and subsequent request will return a 404 since the resource has been deleted.
The key here is to understand that idempotency doesn't mean the response will always be the same, it means that the state of the system will remain unchanged. Lets use this delete request as an example
DELETE https://api-resource/api/v1/delete/1
Since the data with id of 1 has been deleted on the first request, making this request multiple times won't change anything on the system meaning it would always result to the thing, the data with an id of 1 no longer exists.
Extra: The PUT also does the same since making the same call with the same request body would result to the same data being overwritten. Hence nothing changed.
Top comments (4)
What would you say to PUT requests that updates the system by creating log data or even updating certain data like update time in the resource. I believe its not idempotent.
If we start going into details then non of the methods are idempotent.
There's a difference between mathematical idempotency and the REST style ones (or generally in programming). Example is absolute value where calling some function like
abs(abs(number))would always yield same results no matter how many times we called it while passing in the previous result. This is not the rule of REST for idempotency or even programming - depending on what the context is.Another example is a function that increases the value for the input so
increase(number)returns number + 1. In this case it's not mathematically idempotent function becauseincrease(increase(number))will actually result in number + 2, so calling it multiple times will yield different results. This in REST is actually idempotent because we say for given parameter it should always return the same value - which of course means that calling it multiple times likeincrease(number);increase(number)is giving the same result over and over again but not passing in previous result. This is the main difference for REST and programming and mathematics. Even in programming we treat it generally as idempotent as subsequent calls yield same result for the exact same parameter value - so we say it's idempotent because callingincrease(increase(number))is actually changing the parameter so we don't count that as subsequent calls.POST should always create a new record in the system - meaning it should always generate a new row in database or a new file or such things. PUT should NOT create a new record for the given ID if one already exists. Here logs are side effect and record and other properties of a record are not important like updated-date (arguably this could be but we choose to ignore these kind of things). This is more like PUT will not change the ID and same ID is always returned. So updating a record with the same values should always result in those same values persisted on the same record with the same ID (if there is one and there usually is). So it's about abstraction of idempotency not the nit-picking rule of record/value changes. In general sending a PUT request with couple of values would always return a record with those values + the side effects. Given mathematical concept and functional programming ideology this in the end would result in never having idempotent changes because new record should be created each time it's being changed and rest is kept as history. I think this is too much and we should be a bit more flexible and abstract the idea to link it to few things not be so dogmatic about every single statement.
Very explanatory Hasic. Idempotent request methods can end up not being idempotent depending how they are used so its best we focus on their basic usage to understand how idempotency works.
This is a good point Jesse , updating a resource would result to the "dateUpdated" field being updated everytime the resource is updated but one can argue that this only happens in cases that the system tracks when this action takes place. Its the same way that a system can track when last a GET request was made on a particular resource . If nothing is being tracked, the PUT request would be idempotent.