In computing and API design, idempotency is a fundamental concept that ensures operations can be performed multiple times without changing the result beyond the initial application. This principle is especially crucial in networked systems where communication failures might cause requests to be resent. To uphold this principle, our API leverages an idempotentId attribute in some endpoints.

How It Works

When a client sends a request to an idempotent-enabled endpoint of our API, it must include a unique idempotentId attribute within the request. This ID serves as a unique identifier for that particular operation, enabling our system to recognize and prevent the execution of duplicate requests.

IdempotentId

The idempotentId is a client-generated unique identifier that must be provided with requests to certain endpoints. It allows our API to track the operation associated with the request and ensure that it is only executed once, regardless of how many times the request is received.

Error Handling

If a request is sent with an idempotentId that has already been used for a previous operation, our API will not execute the operation again. Instead, it will return an error with the code IDEMPOTENT_ID_CONFLICT and a HTTP status code of CONFLICT (409). This response indicates to the client that the operation associated with the provided idempotentId has already been processed, preventing duplicate operations.

Best Practices

• Generate Unique IDs: Ensure that each idempotentId is unique across the operations where idempotency is required. Utilizing UUIDs (Universally Unique Identifiers) is a common practice for generating these IDs.
• Error Handling: Implement robust error handling on the client side to appropriately respond to IDEMPOTENT_ID_CONFLICT errors, which might involve logging the error or alerting the user that the operation has already been performed.
• Idempotency Key Management: Maintain a record of used idempotentIds for a reasonable period to prevent reuse while ensuring that the storage does not grow indefinitely.