Idempotency & Data Consistency

To ensure safe retries and prevent duplicate operations, the JAVIS API supports idempotency for applicable requests. Additionally, best practices for data consistency help maintain accurate and reliable transactions across multiple API calls.

🔄 What is Idempotency?

Idempotency ensures that making the same API request multiple times has the same effect as making it once. This prevents unintended duplicate transactions due to network retries or client errors.

When to Use Idempotency?

API Operation	Idempotency Required?	Reason
GET /orders/id	✅ Yes	Retrieving data should always return the same response.
POST /orders	✅ Yes	Prevents duplicate order creation.
PUT /orders/id	✅ Yes	Updates should be consistent regardless of retries.
DELETE /orders/id	✅ Yes	Ensures safe deletion, avoiding duplicate delete operations.

🔑 Implementing Idempotency in API Requests

Clients must include an Idempotency-Key in the request header when making POST requests to ensure safe retries.

📌 Example Request (Using Idempotency-Key)

curl --request POST \
  --url "https://api.javis.ai/api/v1/orders" \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000" \
  --header "Content-Type: application/json" \
  --data '{ "customer_id": "CUST001", "total_amount": 100.00 }'

📌 Handling Duplicate Requests

Scenario	API Behavior
Same Idempotency-Key, Same Request	Returns the original response from the first request.
Same Idempotency-Key, Different Request Data	Returns 409 Conflict to prevent inconsistent operations.
Missing Idempotency-Key	Treats it as a new operation.

🔄 Ensuring Data Consistency

Data consistency ensures that all transactions are accurate and synchronized across API requests.

Best Practices for Data Consistency

✅ Atomic Transactions – If an operation has multiple steps (e.g., payment + order creation), ensure that either all steps succeed or none do (rollback on failure).
✅ Optimistic Locking – Prevent race conditions by requiring a version field when updating records. ✅ Eventual vs. Strong Consistency – Choose the right approach based on the business need. ✅ Error Handling for Partial Failures – Implement proper rollback mechanisms if one part of a transaction fails.

❌ Error Handling for Idempotency

If an Idempotency-Key is reused with different request data, the API returns:

{
  "status": "error",
  "error": {
    "code": 409,
    "message": "Idempotency-Key conflict: request data does not match the original request."
  }
}

If a client fails to provide an Idempotency-Key for a required operation:

{
  "status": "error",
  "error": {
    "code": 400,
    "message": "Missing Idempotency-Key in request headers."
  }
}