Is your API idempotent?

You would frequently find senior engineers asking this question in your code review. But what exactly is idempotency?

Idempotency is basically operations that when done once or multiple times, gives you the same result.

Have you used this two-way switch? If yes, do you think this is idempotent? (Last I heard, senior engineers were not happy with the designer of this switch. Apparently, the switch designer skipped the review meeting 😉

If your answer is no, you are right. This two-way switch is not idempotent. Because you can not guarantee that pressing this switch down will always light up the room.

Now, think about the switch in the image above. Is this idempotent? Yes. Because if you press it down, it will always switch off the light, irrespective of how many times you do it. That’s not the case in the case of first example of the two-way switch.

But why is idempotency important?

It’s important because we have to plan for failure. Suppose, you are making a payment and you see this loading screen.

You wait for payment confirmation but this loading screen goes on and on. After a minute (usually the set timeout). The app shows payment pending for your order and you don’t know what just happened? You will wonder the following questions:

Is the amount deducted from the bank?
If the amount is deducted, why is it showing payment pending?
Should I retry the payment?

And what could have gone wrong?

Did the e-commerce site fail to get payment confirmation from the payment partner?
Did the request fail from e-commerce site to the payment partner?
Did the e-commerce backend fail to notify the frontend?

Any of these possibilities could happen, because of maybe high load, network glitch, or any other factors.

Let’s assume for the sake of discussion that e-commerce site fails to get payment confirmation from the payment partner. Now, if you are retrying and the money has been deducted from your account, idempotency at the bank end could save you from double payment for the same order.

But how could banks achieve such idempotency?

One possible way could be the use of the idempotency-key. Consider the curl below:

curl https://api.bank abc.com/v1/payment \

-H “Idempotency-Key: SDFGHJKL123456fgh” \

-d amount=1000 \

-d currency=INR \

-d customer=cus_A8Z5MHwQS7jUmZ

The Idempotency-Key in the header here will likely be a unique key in the bank database table. And it will not allow double payment against the same key. However, it is the duty of e-commerce companies to ensure that they generate the same Idempotency Key for the same order (maybe order Id).

How to use idempotency to your advantage?

Retry

Retry, whenever you don’t get a response from the remote service. Because if you don’t, you would have your transaction in the hanging undesirable state. Make sure that you retry using some idempotency key, this would safeguard you against the danger of double transaction.