Idempotency
Idempotent Requests
An idempotent operation implies that executing it multiple times with the same input parameters doesn't alter the outcome beyond the initial application.
Creation and update (POST and PUT) requests have the capability to be idempotent when the primary token is specified in the header. This allows the caller to retry a call to create an object without inadvertently creating several copies of it.
To execute an idempotent request, include an additional x-idempotency-key: <key> header in the request. <key> is determined by the calling app.
For instance, if you issue a POST request to create a resource and do not get a response due to a card network timeout,
you can reissue the identical call, with the same content and header token, and you will receive a 201 success response.
Warning
- path
- method
- Query parameters
- body
If all these fields as well as the idempotency key are identical to a previous recent request, the duplicate will be ignored.
A unique key is generated from all those values to determine the unicity of the request call.
Kulipa's idempotency functionality operates by storing the resulting status code, headers and body of the initial request made with a specific idempotency key, irrespective of its success or failure for 24hours.
Follow-up requests utilizing the same idempotent combination yield identical results.
How to create it
An idempotency key is a distinct identifier, created by the client and used by the server to discern multiple executions of the same request.
The means of generating unique keys rests with you; however, use of UUIDs(V4), or other high entropy random strings like SHA256 to prevent duplicate keys, is advised.
Idempotency keys can be composed of a maximum of 64 characters.
It is up to the client to ensure identical requests have the same idempotency key, whereas different requests have different keys.
Example
curl -X POST https://api.kulipa.xyz/v1/cards \
-H "Content-Type: application/json" \
-H "x-api-key: apiKeyXxx"
-H "x-idempotency-key: WQ45f889Uuenl4s6f88asw4e5"
-d firstname="johnny boy"
The idempotent operation identifier will be the hash result of ['WQ45f889Uuenl4s6f88asw4e5', 'https://api.kulipa.xyz/v1/cards','POST','','{"firstname":"johnny boy"}'].
const idempotentIdentifier = Hash([
'WQ45f889Uuenl4s6f88asw4e5',
'https://api.kulipa.xyz/v1/cards',
'POST',
'',
'{"firstname":"johnny boy"}',
]);
// idempotentIdentifier === '36206ec3e59acf7cfdce644cf1782ec910423de74f8bcfdcd65b280a8e0e4065'