Idempotency, one of the key features any Web API should have. The idea is that software is unrealiable, the network can fail, the database the API connects to could be offline, the API itself could be performing an intense operation that impacts performance. For all these reasons an API client may resubmit a request, not much of a problem if you are dealing with GET, HEAD, PUT or DELETE, these HTTP methods are idempotent, POST and PATCH on the other hand are not.

An HTTP POST to an orders API will create a new order every time the API gets called. This behavior is not desired, after all, your customers are not going to be happy to see that they have been charged for multiple orders. For this reason, it is essential that when you create a Web API, an effort should be made into making all POST and PATCH requests idempotent.

Two techniques have surfaced over the years on how to make POST and PATCH idempotent. The first technique involves having the API provide the client with a one-time URI. This one-time URI will come with an embedded token. The idea here is that the API can track each token in order to determine if the request is being submitted for the first time or if the request has already been processed or is being processed.

A more popular technique, evangelised by Stipe, comes in the form of using an Idempotancy-Key header. In this approach, the key is generated using V4 UUIDs, to guarantee enough randomness, the client is then responsible for including this header on all POST and PATCH requests, and like in the first technique, the server is responsible for determining if the request is being submitted for the first time or if the request has already been processed.