Background Image

HTTP Idempotency

Insanity is doing the same thing over and over and expecting different results


Have you ever accidentally clicked on the order button twice on any e-commerce and you still ordered a single order? Well, you have idempotency to thank for that (And the developer who implemented it 👨‍💻)! So what is Idempotency? Although it looks like a complex term, it is a pretty simple concept.

Insanity is doing the same thing over and over and expecting different results. - ‘Albert Einstein’

Client-Server Idempotency

Basically, for HTTP API design, when an idempotent API is called twice with the same data, you won’t run the same operation twice. So if the client/frontend calls twice a PUT API to update a user’s data, the server/backend would recognize it is the same request and update the data only once.

Why would I need it?

The reason a client would call the server twice might mostly not be because a user clicked a button two times. It is attributed more to network failures. For example, if an acknowledgment response for the update is NOT returned because of a network failure, the client might automatically send the same request again. Since from its point of view, the update request itself hasn’t arrived at the server.

Safe vs Idempotent

Another classification of HTTP methods to consider is safe methods. Safe methods are methods that do not change any resource on the server, i.e. queries.

The difference is that idempotency is concerned with that we can call the same response many times and get the same response. While safe methods are concerned with keeping the same state of the resources on the servers with the first or the hundredth response as it treats resources in a read-only fashion.

Idempotent, Safe and non-idempotent HTTP Method

In the following table, we can see where each commonly-used HTTP methods fall in the previous categorization

Method Safe Idempotent
GET Yes Yes
HEAD Yes Yes
PUT No Yes

This shows that the real difference between Safe and Idempotent concepts is clear when we look at the behavior of PUT and DELETE methods.

The DELETE method is not safe as it changes the resource/server state by deletion. However, it is idempotent because if we call DELETE on /user/1 for example to delete a user with an ID of 1 the server shouldn’t go and delete the user with an ID of 2 if it doesn’t find it, and it will reply with 200/204 as well since although it didn’t find it it’s still not a fault to call it twice as we have seen earlier.

The PUT method follows the same idea, it replaces a whole object with another whole object or adds a new one so it will reply with the same response each time, but each time it’s doing an update query on the server.

How will this matter to me/my team?

From a backend/server-side perspective, you have to respect the HTTP method and use them correctly according to its semantic meaning. Thus, a GET method, for example, must not change a state as it is safe and must not change in the response type it returns as it is idempotent.

From a frontend/client-side perspective, you can call any idempotent endpoint many times with no fear of misbehavior given your backend team is following the HTTP specs and semantics correctly.