​
Idempotency in the Onsi API

When integrating with the Onsi API, ensuring that your requests are idempotent is crucial for maintaining data integrity and consistency, especially in environments susceptible to network issues or when dealing with operations that should not be duplicated. Idempotency ensures that multiple identical requests will have the same effect as making a single request.

​
Understanding Idempotency

An idempotent API operation can be called many times without different outcomes, no matter how many requests are made. This is particularly important for POST, PUT, and DELETE requests which modify data.

​
Implementing Idempotency with x-idempotency-key

The Onsi API supports idempotency for safe and unsafe HTTP methods through the use of the x-idempotency-key header. Clients should generate and attach this key to requests that need to be idempotent. Here’s how it works:
  • Key Generation: The client generates a unique key for each operation. This key is typically a UUID, but it can be any string you desire.
  • Key Usage: The client includes this key in the HTTP header x-idempotency-key when making a request.
  • Server Processing: On the server side, the API checks if a request with the same idempotency key has been processed before:
  • If yes, and the previous request was successful (returned a 2XX status code), the server will not reprocess the request but will return the result of the previous request.
  • If no previous request with that key exists, the server processes the request as normal.
Idempotency keys will be respected for 7 days after the initial request. After this time, the key will be considered expired and the request will be processed as normal.

​
Benefits of Using x-idempotency-key

  1. Avoid Duplicate Processing: Protects against creating duplicate resources or performing the same operation twice.
  2. Reliability: Enhances the reliability of the API by ensuring that retries due to network failures or other issues do not result in unintended effects.
  3. Consistency: Ensures data consistency, especially in distributed systems where multiple requests might overlap.

​
Example: Creating a Member with POST /v1/members

Below is a simple example of how to use the x-idempotency-key when creating a new member via the /v1/members endpoint.

​
Request:

curl -X POST https://api.onsi.com/v1/members \
-H "Content-Type: application/json" \
-H "x-idempotency-key: 83e41c7e-f7b5-4e06-be92-2a8f2f3b4c68" \
-d '{
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.doe@example.com"
    ...
}'

​
Response:

{
  "email": "jsmith@example.com",
  "memberId": "mem_q5sdae3se6eg9m9dcvug",
  "firstName": "John",
  "lastName": "Smith",
  "phone": "+447123456789",
  "tier": "Gold",
  "workerId": "ID_123",
  "status": "active"
}
In this example, if the request is accidentally sent twice with the same x-idempotency-key, the Onsi API will recognize that the operation has already been performed and will not create a duplicate member. Instead, it will return the details of the member created by the first request.

​
Conclusion

Using the x-idempotency-key in your requests to the Onsi API is a best practice that should be adopted to ensure the robustness and reliability of your application. By implementing idempotent operations, you safeguard your API interactions against unintended duplications and provide a more stable and consistent user experience.