The importance of maintaining idempotency in designing Restful APIs

Too often when working in an Agile environment, developers get tasked with "extra hidden features" that aren't properly described or refined. Ask yourself the following questions: How often were you asked to create an API that does one thing, but also do something extra if some conditions are met?

When creating an API that maintains its idempotence characteristic, we avoid the hassle of figuring out side-effects or hidden "features" that we don't expect when executing a call to an API

What is idempotent?

Idempotent is defined as the effects in which resulting from an API execution is truly independent from all the other executions regardless of how many times the API call was executed. In short, no matter how many times an API is called, it should behave the same.

Let's take a look at an example:

I have $1000 in my bank account at 9:00AM on a Monday morning, when I check my bank account again at 9:05AM, I should still have $1000 unless some actions have been performed on my bank account. I will still have $1000 if I check again next week, next month, ..., until some action has changed the STATE of my account.

In principal, me looking at my bank account can be compared to a simple HTTP GET request. When I am getting a resource, I expect my resources to stay idempotent regardless of how many times I am executing that HTTP GET request.

Why should we care about idempotency in Restful APIs?

One major beneficiary to idempotency is fault-tolerance. When we execute the same API request twice in a row, we expect the result to not break the system. It does not matter what the request is nor how many times it is executed, it should not at any point break our system.

Another beneficiary is the ease of maintainability and documentations of our API. Restful APIs are designed in a pattern in such a way that simply by reading out API, we should have a solid understanding of what it does without side effects.

How?

So how do we manage to keep our APIs idempotence? Simple, there are a few HTTP methods are must maintain its idempotency; these are: GET, PUT, HEAD, OPTIONS, TRACE. POST, PATCH are not idempotence by trait. DELETE is a special case depending on our implementation of the API.

GET and PUT are simple. An API executing a GET request should not at all execute any change to our system; it should be treated simply as the messenger for our client. PUT requests are simply APIs to update/create a resource. The first time a PUT request is executed, it simply create the resource. The N times that the same PUT request is executed, it should simply be overriding that same resource that was created on the 1st request.

POST and PATCH are simple to understand. Both acts as the API to upsert an existing resource, however these do not maintain idempotency like PUT because each request sent could be doing something different, hence resulting in a different change of STATE in our system

DELETE is weird. Simply put deleting a resource the first time will result in a 200/204 status code. Deleting the N+1 time will result in a 404 message, thus is semi-idempotence (or it is idempotence after the first time). However if we have a DELETE api to delete based on some conditions, then this API is no longer idempotent.

In conclusion, idempotent APIs act as not just an ease of maintainability tool, it also acts as a fault-tolerance patterns where APIs should and can only function exactly as it is designed to be.