Idempotency

Introduction

Idempotency is important in building fault-tolerant HTTP APIs. An HTTP request method is considered idempotent if the intended effect on the server of multiple identical requests is the same as the effect for a single such request. HTTP methods OPTIONS, HEAD, GET, PUT and DELETE are idempotent by their nature while POST and PATCH require special handling in order to ensure idempotency.

Why Idempotency?

Consider a scenario where the client sends a POST request to the cubiX platform to create a book transfer, but the client gets a timeout before receiving the response. The following questions arise: Was the book transfer actually created? Did the timeout occur during sending of the request, or when receiving the response? Can the client safely retry the request, or does it need to figure out what happened in the first place? With idempotency enforced, such questions can be safely resolved by retrying a request until a response is received from the cubiX platform with no risk of creating a duplicate transfer.

x-idempotency-key

An idempotency key is a unique value generated by the client which the cubiX platform uses to recognize subsequent retries of the same request. This value is passed in the x-idempotency-key HTTP request header.

HTTP

POST /transfers/v1 HTTP/1.1
Host: cubi-sandbox-api.customersbank.com
Authorization: ******
x-idempotency-key: 2A8F9A35-02B4-4394-8E1F-F98CEC5FBA9A
{....}

Client Responsibility

• Clients MUST include an idempotency key for all POST and PATCH methods unless the method is specifically not noted as required in documentation
• The idempotency key value MUST be unique and MUST NOT be reused with another request to the same method with a different request payload
• The idempotency key MUST be a valid UUID v4
• Clients SHOULD NOT include an idempotency key for GET, PUT, DELETE, OPTIONS and HEAD methods.
• Clients MUST NOT include more than one x-idempotency-key header in a single request

cubiX Idempotency Evaluation

1. Is this a first-time request? - Key has not been seen before.

   Process request normally and send response

2. Is it a retry request? - Key has been seen before and the request was retried after the original request completed.

   The cubiX platform will skip processing the request again and respond with the result of the previously completed operation.

3. Is it a concurrent request? - Key has been seen before, but the request was retried before the original request completed.

   The cubiX platform will skip processing the request again and respond with a resource conflict error (409 status code).

NOTE: cubiX is only storing idempotency keys for 48 hours, if a key is re-used 48 hours after the initial request, the request would be processed as if the key had not been sent before.

Error Scenarios

1. Missing x-idempotency-key

   If the key is required and no x-idempotency-key header is present, the cubiX platform replies with a 400 Bad Request status code.

   HTTP

   HTTP/1.1 400 Bad Request
   Content-Type: application/problem+json
   { 
    "title": "x-idempotency-key is missing",
    "detail": "This operation is idempotent, and it requires correct usage of x-idempotency-key."
   }
   

   
   

2. Reuse of Idempotency Key with different payload

   If there is an attempt to reuse an idempotency key with a different request payload, the cubiX platform replies with a 422 Unprocessable Entity status code.

   HTTP

   HTTP/1.1 422 Unprocessable Content
   Content-Type: application/problem+json
   {
    "title": "x-idempotency-key is already used",
    "detail": "This operation is idempotent, and it requires correct usage of Idempotency Key. Idempotency Key 
            MUST not be reused across different payloads of this operation."
   }
   

   
   

3. Retried request while still processing

   If the request is retried while the original request is still being processed, the cubiX platform replies with a 409 Conflict status code.

   HTTP

   HTTP/1.1 409 Conflict
   Content-Type: application/problem+json
   {
    "title": "A request is outstanding for this Idempotency-Key",
    "detail": "A request with the same Idempotency-Key for the same operation is being processed or is outstanding.",
   }
   

   
   

4. More than one x-idempotency-key header

   If more than one x-idempotency-key header is present, the cubiX platform replies with a 400 Bad Request status code.

   HTTP

   HTTP/1.1 400 Bad Request
   Content-Type: application/problem+json
   {
    "title": "x-idempotency-key",
    "detail": "Header cannot contain more than one x-idempotency-key field"
   }