API Idempotency

Payment Service Providers like Stripe and Checkout.com support idempotent APIs.

But what is idempotency?

Idempotency ensures that if we call an API multiple times with the same request, it gives the same result.

First, let's take a look at how a non idempotent API would behave. We will use a Payments Service API as an example. This API allows Person A (Yoda) to send money to Person B (Han Solo).

1. Yoda sends a HTTP post payment request ($100 to Han Solo) to the Payments API.
2. The Payments API performs some operations against the database.
3. A successful response is returned back to Yoda meaning Han Solo has been paid $100.

What if the exact same request was sent again to the Payments API?

If the API is not idempotent then it will process the same request again and Yoda will be charged twice ($100 to Han Solo for the first request and then $100 for the second request). Also HTTP Post is not idempotent.

Another thing to consider is failures such as network glitches. These kind of failures can occur anywhere in the flow.

1. Yoda sends a HTTP post payment request ($100 to Han Solo) to the Payments API.
2. The Payments API performs some operations against the database which is successful.
3. On returning a response to Yoda, there is some network glitch which returns an unsuccessful response

Should Yoda retry the request?
Although this request was successful on the API side, Yoda is unaware of it on the client side. If the API is not idempotent then retrying the same request again will lead to Yoda being charged twice again.

We therefore need a mechanism to handle Yoda being double charged. Let's see how idempotency can solve these problems.

The flow for an idempotent API is as follows:

1. Yoda generates an idempotency key (usually a UUID)
2. The idempotency key is sent in the header as part of the request to the Payments API
3. The Payments API stores the idempotency key in the database
4. A successful response is returned back to Yoda meaning Han Solo has been paid $100.

Since the API is now idempotent, if the same request is sent to the Payments API, it will check if the idempotency key exists in the database. If it does then this means that it is a duplicate request and will ignore it. Otherwise if the request contains an idempotency key that is not in the database then it is treated as a new request. The same flow applies with request failures and retries.