Introduction

An HTTP request method is considered "idempotent" if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request. According to [RFC7231], HTTP methods "OPTIONS", "HEAD", "GET", "PUT" and "DELETE" are idempotent while methods "POST" and "PATCH" are not.

Let's say a client of an HTTP API wants to create (or update) a resource using a "POST" method. Since "POST" is NOT an idempotent method, calling it multiple times can result in duplication or wrong updates. For many use cases of HTTP APIs, duplicated resources are a severe problem from a business perspective.

The HTTP Idempotency-Key request header field can be used to carry idempotency key in order to make non-idempotent HTTP methods such as "POST" or "PATCH" fault-tolerant (see full specification here).

Syntax

Add “Idempotency-Key“ header to POST or PATCH request:

Idempotency-Key = <string_value>

The following example shows an idempotency key using "UUID" [RFC4122]:

curl -X 'POST'  
  '<https://api.fortressapi.com/api/trust/v1/payments'>  
  -H 'accept: application/json'  
  -H 'Content-Type: application/json'  
  -H 'Idempotency-Key: 285e197c-b580-45f4-8c5f-7c27ac73e221'  
  -d '{  
  "source": {  
    "custodialAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"  
  },  
  "destination": {  
    "custodialAccountId": "1487ac29-cd90-4abd-a925-b0c1cb183765"  
  },  
  "comment": "",  
  "funds": 100,  
  "useIsa": false  
}'

Restrictions

Uniqueness of Idempotency Key
The idempotency key that is supplied as part of every "POST" endpoint and could be used exclusively for it. But the same idempotency key could be reused on different endpoints while maintaining guarantees within the each one separately.

Idempotency Key Validity and Expiry
The resource may enforce time based idempotency keys, thus, be able to purge or delete a key upon its expiry.

Idempotency Fingerprint
An idempotency fingerprint may be used in conjunction with an idempotency key to determine the uniqueness of a request. Such a fingerprint is generated from request payload data by the resource server.