TRENDING

TECHNOLOGY NEWS FROM AROUND THE WORLD

→
Idempotency keys in Web APIs: safe retries without duplicate writes
Software Engineering · 2015
Software Engineering2015

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.

Yazılımcının GünlüğüPublished: Nov 16, 20263 min read

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.

0 reads

Comments

No comments yet. Be the first to contribute.

✎ Write a comment

Your comment appears after submission; spam and duplicate submissions are blocked.