Idempotent Requests
Idempotency is supported by all POST APIs, which allows you to retry requests and avoid mistakenly repeating the same one. When an API call is interrupted in transit and you don't get a response, this is handy. If, for example, a network connection fault prevents you from receiving a response to a request to create a customer, you can retry the request with the same idempotency key to ensure that no duplicate customers are generated.
To facilitate idempotency clients are recommended to provide an additional idempotency-key: <x-request-id> header to the request.
The idempotency key is expected to be a unique value generated by the client that the server would use to recognize subsequent retries of the same request. While clients are free to use their logic to create the unique key, we would strongly recommend using V4 UUIDs, or any other random string with enough entropy to avoid collisions. The Idempotency keys can be up to 255 characters long.
NIUM's idempotency works by saving the body of the first request made, along with the resulting status code when received regardless of whether it succeeded or failed, for any given idempotency key. Any subsequent requests with the same key will return the same result, including 500 errors.
All idempotency keys will be eligible to be removed from the system automatically after they're at least 24 hours old, and a new request will be generated if a key is reused after the original key has been purged.
Results will only be saved if an API endpoint had started executing. If the request conflicted with another that was executing concurrently, no idempotent result will be saved as no API endpoint began execution and clients can expect to get the response for the original request.
All POST requests would accept idempotency keys and sending idempotency keys in GET and DELETE requests will have no effect and should be avoided, as these requests are already idempotent.