What Is an Idempotent API?

When you make a payment online, you expect it to process without double charging your card. If it does double charge you, this creates a negative customer experience that may push you away from the business forever — costing the company your lifetime value as a customer. 

If you are on the other end of this transaction, building the API to process payments, you can use the API idempotency to prevent issues like this from happening in the first place.

In this article, we will discuss idempotent APIs and why they are important in your REST API building process. If you do not know what idempotency is with regards to APIs, then this article is going to give you some great insight that can help you create a better customer experience on your website.  

An Introduction to Idempotent REST APIs

As a developer, you want to ensure when an identical request is sent to the server, the intended result is achieved without changing the end result. The idea is to build resilient APIs that can recover from failure effectively. Take a look at the example API calling process.

In the above example, the client is making an API call to the server. When the client calls the API "create payment" we can get a number of possible responses such as success, failure, dependency issues, or no response. In this case, we received the message "no response."

It is natural to deal with a "no response" issue by retrying the API call. This is usually a good way to give the server some time to recover from issues like dealing with multiple requests at one time. But, how do we know that the original request to "create payment" didn't actually succeed in the backend?

Once we retry the API call again after we received no response, it is possible that we could have two different payments when we only wanted one. This can cause a problem. We want to build resilient APIs by supporting this notion of automatic retries. In order to do so, we must make our APIs idempotent.  

What is idempotent API?

Idempotent implies that a certain operation can be applied many times, without changing the result. Essentially, it is like multiplying a number by zero. No matter how many times you multiply a number, the result will always be 0. In order to change the result, you need to change the operation.

In the example above, if you call "create payment" multiple times, you should still get one payment. That is the type of behavior that an idempotent operation supports.

What is an idempotent REST API?

When an HTTP method is idempotent in a REST API, this means that if you send multiple identical requests, only the initial request would cause a change. Therefore, the results returned to the user will not depend on how many times the method has been called.

Idempotent HTTP Methods    

Some REST APIs are naturally idempotent while others aren't. To be considered idempotent, only the back-end state of the server is considered. The following table illustrates the HTTP methods and their idempotence state.  

As you can see from the table POST and PATCH APIs are not idempotent. On the other hand, HEAD, OPTIONS, GET, PUT, TRACE, and DELETE are idempotent. Let's take a closer look at each of these methods to determine the reason for their idempotent state.

GET | HEAD | OPTIONS | TRACE

GET is an idempotent method because it is only a read operation and doesn't cause any state change in the backend. If GET/payment endpoint is called through multiple identical requests, you would get the same response every time just as you got the first time.

The same principle applies to HEAD and OPTIONS since they are used to retrieve data. They never change the resource state on the server.

TRACE can also be idempotent, but it's not always guaranteed. It's more of an expectation rather than an actual requirement. 

POST

POST is not an idempotent method since calling it multiple times may result in incorrect updates. Usually, POST APIs create new resources on the server. If POST/payment endpoint is called with an identical request body, you will create multiple records. To avoid this, you must have your own custom logic preventing duplicate records.   

PUT

PUT is an idempotent method because it updates a record. If PUT/payment endpoint is called with an identical request, it will result in no state change other than the first request.  

DELETE

DELETE is an idempotent method because consecutive similar requests wouldn't change the delete state. The first call of a DELETE may return a 200 (ok), but additional DELETE calls will likely return a 404 (Not Found). The response is different after the first request but there is no change of state.  

PATCH

Patch is not typically an idempotent method because if you perform a consecutive series of move operations on a JSON tree with the same payload like { “op”: “move”, “from”: “/tags/main”, “path”: “/tags/sub” }, the first one will cause the move operation to happen and the consecutive ones will cause errors. Unlike PUT which updates the entire record, PATCH can be used to update only certain fields in a record.

Why are idempotent APIs important?

It is important that your REST APIs follow idempotent guidelines because it is a common industry standard. The user of your APIs will assume that your endpoints behave as standard. APIs support idempotency for safely retrying requests without mistakenly performing the same operation twice. Now, if your peers say that you need to make an endpoint idempotent, you will know exactly what they are talking about.