The Role of Idempotency in API Design
Let's learn about idempotency and its need in API design.
Introduction
Idempotence is a concept where clients get the same response against multiple identical requests. Using idempotence, calling endpoints any number of times results in the call occurring only once. This is an important concept because it ensures that if a client repeatedly sends the same request, then the server state remains the same after the first call.
Before we discuss a practical example of idempotence, let's understand idempotence with the help of the following mathematical function:
f(x) = x^3 + 6
For the equation above, if x = 4, then f(x) is equal to 70. The f(x) value will not change as long as x remains 4. This means that the equation above is idempotent for x = 4. In the same way, an API is idempotent if the response remains the same for all identical incoming requests.
Let’s consider the Twitter API that deletes a Tweet. Upon receiving the client's request for the first time, the server should delete the Tweet. For similar subsequent requests, the server's state should not change, and the response for the client should remain the same. Take a look at the illustration below for an illustration of the described behavior.
In the illustration above, the server performed the intended action only once. But on the second request, the server sent the same response from the cache. Therefore, it doesn’t matter how many requests a client initiates to delete a particular Tweet, it gets the same response from the server. The table below highlights some advantages and disadvantages of APIs that are idempotent.
Non-idempotent API | Idempotent API's advantages | Idempotent API's disadvantages |
Overloads the server by repeatedly requesting for same resources (multiple requests) | Reduces load on the server | Extra storage is required to cache the responses and keys of the responses |
Causes data redundancy by accepting all the requests and sending the same data repeatedly | Eliminates data redundancy | Custom scheduling job (custom code) is required to define TTL and then clear the data from storage |
Due to the repetition of the same requests, networks can get busy, and congested | Avoids network congestion | In case of using third-party scheduling jobs (TTL and clearing storage jobs), it adds the overhead of integrating them |
These are resource wastages because they’re occupied in responding to the same requests again and again. | Efficient resource utilization | - |
Now, we’ll go into the details of some examples of the cases specified above.
Why does idempotence matter in API design?
One attribute of a good API is that it functions according to the
Reliability: Provides reliability when identical requests are forwarded to the servers by a client.
Consistency: Ensures consistency by ...