Idempotency

Our system supports idempotency to retry requests without the risk of performing the request multiple times. This is especially useful in situations where there is a network outage, and you aren’t sure if a previous request has been processed successfully.

With an idempotency key, a unique value generated by the client, that our server recognizes subsequent retries of the same request. This guarantees that retrying a request with the same idempotency key doesn't result in another execution of the endpoint.

Idempotency saves the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same idempotency key return the same cached results of the original request, including errors.

The idempotency key is not permanently saved in our system. A previously processed request is determined by a duplicate value in the combination hash of user client id from the token, URI endpoint, idempotency-key, and request-body. If the request body is modified in any way and re-sent, it won't be seen as a duplicate request and is processed normally.

Therefore, if the intent is to process the request a second time, the idempotency key should be changed to a new value.

Idempotency keys are eligible to be removed from the system automatically after they're at least 24 hours old, and a new request is executed if a key is reused after the original has been pruned. The idempotency layer compares incoming parameters to those of the original request and errors unless they're the same to prevent accidental misuse.

Results are only saved if an API endpoint started executing. If incoming parameters failed validation, or the request conflicted with another that was executing concurrently, no idempotent result is saved. This is because no API endpoint began execution. It is safe to retry these requests.

Our server has an idempotency middleware. This middleware checks each of the requests coming into the application to see if the idempotency key is present in the headers.

If the idempotency-key is present in the request, it queries the database to check if there’s a record corresponding to that idempotency-key. If there is, the middleware stops any further execution in the middleware layer itself, and immediately responds with the saved data as a response.

Otherwise, it continues to the application layer and creates a new record in the database with the Idempotency key and the generated response, and finally return the same response to the client.

A previously processed request is determined by a combination of same endpoint, request body and idempotency key. If the request body is modified in anyway, it will not be seen as a duplicate request and will be processed normally.

Every time a request is made with an idempotency key, the server saves resulting status code. Because it is a unique value, the server uses that information to recognize subsequent retries of the same request.

All POST requests accept idempotency keys. Make sure to include a unique key in your request to protect against accidental duplicate requests.

PUT, GET and DELETE requests are naturally idempotent and there is no value in adding an idempotency key. The key is ignored if present in these requests.

To perform an idempotent request, you must provide an Idempotency-Key: 'xxxxx' in the header

You can detect if a request is being handled as a duplicate and returning a cached response, by looking for the original-request-id response header. If an original-request-id value appears in the response header, it means the request has been handled as a duplicate.

The original-request-id value correlates to the CR generated request-id of the original request processed under the idempotency key provided.