Idempotency, in the context of web APIs, ensures that an operation can be performed multiple times without changing the result beyond the initial application. In simpler terms, if you send the same request multiple times, the server will recognize and process it only once. This is particularly valuable in situations where network failures or other issues might cause clients to retry requests.
How does it work ?
Idempotency is not enforced for the Izix API at the moment but we highly recommend to implement it by design in your developments.
Why Is Idempotency Important?
- Reliability: Idempotency provides a safety mechanism against network and application errors that might cause multiple submissions of the same request.
- Consistency: It guarantees that the state of the server remains consistent, regardless of how many times a client sends a request.
- User Confidence: Users or client applications can retry operations without the risk of causing unwanted side effects, which builds confidence in the system's robustness.
How to Implement Idempotency in Your Integration with Izix API
Step 1: Generate a Unique Idempotency Key
The first step in making an API request idempotent is to generate a unique key for every operation. This key, which is typically a V4 UUIDs, or another random string with enough entropy to avoid collisions, identifies the request uniquely. ( Idempotency keys are up to 255 characters long.) You should generate this key in your client application before making the request to the API.
Step 2: Include the Idempotency Key in Your Request
When making a request to the Izix API, include the idempotency key in the request headers. This allows the API to recognize and handle the request appropriately. All HTTP methods susceptible to create or modify data support idempotency keys 'POST', 'PUT', 'PATCH', 'DELETE'.
Idempotency-Key: KG5LxwFBu7Yn2KHyTDStep 3: Server Handling of the Idempotency Key
The server-side logic of the Izix API will check for the presence of an idempotency key. If the key has been seen before, the server retrieves the result of the original request associated with that key and returns it, instead of performing the operation again. This logic is maintained on the server to ensure that duplicate requests result in the same outcome.
Best Practices for Developers
- Key Storage and Expiration: Store keys temporarily but long enough to handle any retries. Typically, keys might be stored from 24 hours to a week.
- Key Uniqueness: Ensure each operation has a unique key. Avoid reusing keys across different types of operations.
- Error Handling: Implement error handling to manage the response when an idempotency key is reused, especially when the initial request resulted in an error.