Defining Idempotence
According to Wikipedia idempotence is described as:
The property of certain operations in mathematics and computer science whereby they can be applied multiple times without changing the result beyond the initial application.
Now that could be the end of this blog post, however we need to look further into what this means when it comes to Software development. The term API will be used in this post interchangeably with methods, functions and HTTP/REST calls. You can implement idempotence on any of these abstraction levels, whether you are calling a method or an external endpoint.
What is Idempotence?
If an API is idempotent you can call it twice with the same values and get the same result. This concept is easy to understand when it comes to getting a resource from an API call. If we fetch the book with ISBN "978-0135957059" we would expect to get the same book twice. This is idempotent as the same input gives the same result and it does not change the state of the server. However, what should happen if you try to create the same book twice? This is where idempotence gets interesting.
Often if we make a method call to a method twice we would expect that something happens twice or that you get an exception on the second call. However most of the time it is undesirable to create the same resource twice and it is often the result of an error. An alternative to creating it twice would be to fail on the second call, but what will you do with this error? In distributed systems you will often see timeouts, in this situation you do not know if the receiver actually handled your request. From their point of view they may have handled this request, but you never got the response, perhaps because of some network failure or you did not wait long enough for them to finish. The question becomes, do you dare to repeat the call?
If the service or API you are calling is idempotent the answer is yes! You can safely make the same request one more time, as it will yield the same result. If we reuse the example of a book, if you try to create the same book twice it will only create it the first time. It may be that it is "updated" (replaced) on the second call, but since you provided the same data it will give you the same result - the book is the same as in the first call.
In order to do this you need some way to identify that this call is trying to create or update the same resource. To do this, the resource needs to have a unique key that the client can provide. For books, a unique key could be the ISBN number "978-0135957059".
These principles also apply in the scenario where you want to delete a resource. If you call delete twice, it is still deleted when you call the second time so you can give the same result: The resource is gone. In some protocols this may be shown with different return codes, the first may tell that the resource is deleted and the second that there is no resource. However the result and the state of the system is the same. An example could be HTTP, where the first delete request would return 200 (ok) and the second 404 (not found).
In REST / HTTP
You are likely here becuase you are using HTTP (or REST) to communicate in your solution, perhaps you trying to work out the differences between the HTTP verbs, if so please see my blog post on PUT VS POST.
In HTTP the following verbs are known to be idempotent (not a complete list):
- GET
- OPTIONS
- PUT
- DELETE
Of the above, GET and OPTIONS are safe to use, as they never change the state of the resource you are accessing. Whereas PUT and DELETE are unsafe as they alter or remove the resource you are interacting with.
Another common HTTP verb is POST. POST is not idempotent, which means if you make a post request twice with the same input, two resources will be created. If this was to be done with PUT only one would be created, the second request would do "nothing". PUT is becoming more and more popular in distributed systems as the requester does not have to worry about making the same request multiple times. As mentioned previously this is a great feature when timeouts or other network issues occur.
Is it called Idempotency or Idempotence?
Some authors use the term idempotency and others use idempotence. They can be used interchangeably, "Idempotence" has been used for this post since that is what Wikipedia uses.
That is it!
I hope you found this post to be insightful, if so please leave a comment down below! Any other feedback is welcome as well!