Why it matters
Networks drop responses. A client sends a payment request, the server processes it, but the response is lost. The client retries. Without protection, the customer is charged twice. An idempotent API makes a repeated request have the same effect as a single one.
Naturally idempotent verbs
Some operations are idempotent by nature. Setting a value to ten is idempotent because doing it again leaves it at ten. GET, PUT, and DELETE are typically idempotent, while a plain create that adds a new row each time is not.
Idempotency keys
For creates, the standard fix is an idempotency key. The client generates a unique key per logical operation and sends it with the request.
- The server records the key with the result of the first call.
- If the same key arrives again, the server returns the stored result instead of doing the work twice.
- Keys are scoped and expire after a window.
Key idea
Idempotent APIs make a repeated request have the same effect as one, using naturally idempotent verbs and idempotency keys so retries are safe and never double charge.