Summary

The provided content discusses the concept of idempotency in REST APIs, explaining its importance and how different HTTP methods adhere to this principle.

Abstract

Idempotency in REST APIs refers to the property of certain operations that, when performed multiple times, result in the same state of the system as if they were performed only once. This concept, rooted in mathematics, is crucial for API design, as it ensures that repeated requests do not lead to unintended changes. The article delves into the idempotent nature of standard HTTP methods such as GET, PUT, DELETE, and PATCH, highlighting how they align with idempotency expectations. It also distinguishes between safe methods that do not alter the server's state, like GET, HEAD, and OPTIONS, and those that do, such as POST. The article emphasizes the need for API endpoints to follow these standards to meet the expectations of developers and ensure consistency and reliability in API interactions.

Opinions

The author suggests that understanding idempotency is essential for developers working with APIs, as it affects how endpoints are expected to behave.
The article implies that adhering to idempotency standards is not only a best practice but also a necessity for creating APIs that align with industry expectations.
It is noted that while POST is not inherently idempotent, custom logic can be implemented to prevent the creation of duplicate records.
The author points out that the idempotency of DELETE operations depends on whether the deletion is soft (idempotent) or hard (non-idempotent).
PATCH operations are presented as potentially idempotent, but this depends on the specific implementation and whether side effects are involved.
The article concludes by stressing the importance of designing API endpoints that comply with industry standards, which in turn simplifies the work of other developers who utilize these APIs.

What is Idempotency in REST APIs and Why Should You Care?

Illustration from https://illlustrations.co/

Idem-what now?

If you have been working with APIs, chances are that you might have heard some of your peers throw around the word “Idempotence”, leaving you to wonder what they really mean by that word anyway.

In this article we’ll look at a detailed answer; so we could learn what this fancy word “Idempotence” actually means in a REST API context.

After reading this article, the next time when your peer says that you need to make an endpoint idempotent, you will know exactly what they are talking about. So let’s get started:

Mathematics to The Rescue :

The word “Idempotent” has its roots in Mathematics. It just means the following:

An operation is said to be idempotent if it doesn’t change the result even when applied multiple times. The multiple operations will have the same effect leaving us with the same result that we obtained when it was applied initially for the first time.

Let have a look at the below operation:

1*1*1*1*1*1*1*1

Initially, when we multiply 1 with 1 we get 1 as the result. After that, no matter how many times we do the same operation of multiplying with 1, the end result remains the same. Hence this is an idempotent operation.

On the contrary, let’s look at a different operation:

5*5*5*5

The above operation of multiplying by 5 is not idempotent. Because every time the operation is applied, the end result changes. Initially, the result will be 25, on the second application of the operation the result would become 125 and so on. The result is affected and changes if the same operation is applied in succession. Hence the operation of multiplying by 5 is not idempotent.

REST APIs and Idempotence :

When we say an HTTP method is idempotent in a REST API context, we mean that if we send multiple identical requests one after the other, only the initial request would cause a change in the underlying state of the system and all the following requests will leave the state unaltered. Essentially, it is just like multiplying a bunch of 1s. no matter how many times we multiply the end result is always the same.

The following table illustrates the standard HTTP methods and their standard idempotence nature:

If you’re wondering what that “Is Safe” column means, it is just that any HTTP method that doesn’t modify the server’s state is categorized as a safe method. If you look at the table all methods that are supposed to be used to retrieve data (GET, HEAD, OPTIONS) are safe, as their handlers will essentially be a read endpoint.

Explanation:

GET:

Let’s say we have an endpoint GET /articles that give a list of blog articles present in the datastore of the system. If we send multiple consecutive identical requests to this endpoint, we would get the same response every time as we got for the first time. Also, this is just a read operation and doesn’t cause any state change in the backend system. Thus GET is idempotent.

POST:

For POST, however, the standard implementation will be that every call creates a record in the underlying database. If POST /articles endpoint is called multiple times consecutively with an identical request body, we will end up creating multiple records, Unless we have our own custom logic to avoid creating duplicate records.

PUT:

A PUT request is idempotent because it only updates a record. So identical requests will ultimately result in no state change except for the first call.

The Curious Cases of DELETE and PATCH:

DELETE:

A DELETE is idempotent if the resources are soft-deleted by marking the record with a flag, as consecutive similar requests wouldn’t change the deleted state of the record.

However, it is noteworthy to consider that DELETE is non-idempotent for hard-deletes since the second call will result in a 404 not found error, thus violating the principle of idempotency.

PATCH:

Unlike PUT which updates the entire record, PATCH can be used to update only certain fields in a record.

PATCH can be idempotent if the endpoint doesn’t have any other side-effect other than updating a certain field in a particular record. Such as updating the article’s title in a specific record.

But PATCH endpoints can also be used to perform JSON Patching. This means that if we perform a consecutive series of move operation 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. If you think about it, in a way, this scenario is similar to the one that we discussed on hard-deleting resources using DELETE endpoints.

So Why Bother?

One might think, why should we care about this. Well, the answer is, these are the standards for the HTTP methods and when we design an endpoint with these Methods, the end-users of our API (read other developers) will expect our endpoints to behave as per the standards. In some cases, they might even make certain technical decisions in their code assuming that the endpoints we provided them would work as per the standards. That would make sense because, after all, the standards exist for a reason right? So knowing this will help us design our API endpoints that are compliant with the widely accepted industry standards, making lives easier for the people who use those APIs.

Conclusion:

I hope this article furthered our understanding of idempotence in HTTP methods. Thanks for reading my thoughts.

Cheers :)