Understanding Idempotency
As a software engineer, you want to make sure that when a user sends an identical request to the server once, twice, or multiple times, the intended result is achieved and the end result is not changed beyond the initial application of the operation. Idempotence is a property that implies that applying an operation once or multiple times will give the same intended result.
In the web context, an idempotent HTTP method is a method that can make multiple identical requests to the server and the intended change in the server is the same as that of a single request. It also means that the result returned to the client will not depend on how many times the method has been called.
For example, say you have a RESTful API that will DELETE a specific picture from your social media account. Now, if you call the API once, twice, or a million times, the response will be the same and only that one picture will get deleted. The first DELETE request to the server will actually make the intended change in the server. All subsequent requests might return a ‘404’ (Not Found), ‘204’ (No Content), or ‘200’ (OK) status to the client indicating that the request has been completed.
Now, let’s take another example. Say you have a RESTful API that will POST a picture (or a new resource) to your social media profile. While submitting the picture, there is some network issue and the client is not notified if the API call was successful or if it failed. You may try to submit the same picture multiple times, resulting in duplicate resources on the server (and 5 identical pictures on your account!!). Such an API is not idempotent as it results in changing the state of resources on the server each time an identical request is sent.
The main idea of making an API idempotent is to ensure that the same request retries (due to network issues, client errors, etc.) should not cause any unindended side-effects.
Following the REST principles for designing and writing an API, the GET, PUT, and DELETE HTTP methods will be idempotent implicitly. The only methods that are not idempotent by default are POST and PATCH. Here’s where idempotency keys come to the rescue.
Idempotency Key
Taking the above examples that we discussed, consider a scenario where each picture that you want to upload to your social media account has a unique P_ID associated with it. With every POST call, this unique P_ID is sent to the server. The server can add checks to ensure that a request with the same P_ID is not processed multiple times. This will ensure idempotency with the POST request and the P_ID will act as the idempotency key.
An idempotency key is a key generated by the client to indicate retries of a same request to the server. It is sent to the server as part of the request.
The server generally stores a copy of the key. Below are a couple of ways in which the server can leverage the stored idempotency keys:
- In a scenario where a server error occurs and processing is interrupted mid-way, the server can choose to use the idempotency key to re-initiate a transaction from the point it got interrupted at.
- Once it is definitive of the result of the request, the server can store the result (success or failure) along with the idempotency key. If the client tries to again make the same request, the server can short-circuit and return the stored result.
How the idempotency key is designed and created is up to the developer. You can architect your application to use any information to generate the key — current timestamp, random strings, UUID, etc. However, it is recommended to have a mechanism to generate keys which will result in a minimum collision of requests.
Hope this gives you some idea about what idempotency is and how it can be useful for developers to build a resilient system.
