Idempotency keys in Web APIs: safe retries without duplicate writes
A network retry should not create a second payment or order. A request key, payload fingerprint and atomic persistence form the foundation of safe retries.
The uncertainty behind network retries
A client sends a payment request; the server commits the operation, but the response is lost. Retrying may unintentionally create a second order. Missing an HTTP response does not prove the original transaction failed. For effectful endpoints such as POST, the client should send a unique request identifier that the server records with the operation.
Keys, payload hashes and atomic writes
For example, accept an Idempotency-Key header on POST /orders. Persist the account, key, fingerprint of the normalized request body and result state behind a unique constraint. Repeating the same key and payload should return the original outcome; repeating the key with a different payload should produce a clear conflict. Checking the key and recording the effect must be atomic.
POST /orders
Idempotency-Key: 47a03d19-8b5d-4abd-8107-92d36b7db510
Content-Type: application/json
{"productId":42,"quantity":1}Concurrency and expiration
Two matching requests can arrive at exactly the same time, so a SELECT-then-INSERT check is insufficient on its own. Use a database uniqueness constraint, an appropriate transaction and concurrency tests. Define a bounded key-retention policy instead of retaining every fingerprint forever. After expiration, a repeated request may legitimately be processed again; document that limit.
Context and validation
This is a present-day study of reliability problems associated with Web API development around 2015, not a backdated post. Test lost responses, two simultaneous requests and key reuse with a different body. Scope keys to the caller and operation. Reconcile the final count of distinct orders in persistent storage rather than trusting the number of successful HTTP responses.
Comments
No comments yet. Be the first to contribute.
✎ Write a comment