Idempotent Operations

Idempotent operations are designed to safely be run multiple times while always returning the same result. Returning the same result safely avoids performing an action twice unintentionally.

Maintaining idempotency is important if responses from a server are not received by the client. The server may have properly processed a request, but a networking error prevented the client from receiving the response.  The client may make the request again, unaware that the server had successfully processed the request. However, it would cause a problem if the server processed the request again.

For example, a transfer operation should not perform the exact same debit twice. The owner of the account is expecting only $10 dollars to be debited and does not want $20 or $30 dollars debited by accident. An idempotent transfer operation prevents duplicated debit transactions from occurring.

Idempotency Keys

Idempotency can be ensured with the use of a idempotency key, a unique identifier (such as a UUID) that is sent with the request. When the server receives the request, it uses the idempotency key to make sure the request is not executed more than once.

A retried request must include the same idempotency key that was sent with the original request. The server receiving the request notices that this idempotency key matches a previous request. The server sends back the same response it attempted to send during the original request but does not do any of the work that was requested. This prevents the server from accidentally performing the same action twice resulting in problems such as duplicated data.

For example, the server may have gotten the following requests around the same time:

1. Transfer: -$10, Key: 12345

2. Transfer: -$10, Key: 54321

3. Transfer: $15, Key: 98765

4. Transfer: -$10, Key: 12345

Only two of them have the same idempotency key. Request #4 shares the same key as request #1, and would not cause another debit to occur. The server would simply send back the same response it had sent the first time it processed the request without performing the actual debit.

It is important that the idempotency key be unique for each distinct call to an operation. In the above examples, a 5-digit code is used, but in reality that would not be unique enough for an idempotency key. Using a V4 UUID for the idempotency key is recommended.

Certain operations are guaranteed to be idempotent but do not require an idempotency key, such as GET, PUT and DELETE. For instance, there is no need to enforce idempotency deleting data: data cannot be deleted twice.

Apiture API Idempotency Keys Notes

• Apiture recommends a V4 UUID for idempotency keys but does not require it.

• The Idempotency key should be included in the header named Idempotency-Key. See The Idempotency-Key HTTP Header Field for more details.

• Apiture removes stored idempotency keys after 24 hours.

• Apiture only compares the idempotency key to previous requests, not the data contained in the request.