Glossary / Idempotency
Idempotency
An operation is idempotent when repeating it with the same intended request has the same externally observable effect as performing it once. Idempotency is essential for safe retries when clients cannot tell whether a request failed before or after the server committed it. It is a property of the operation and its contract, not merely an HTTP verb or client library setting.
Designing idempotent operations
A read is often naturally idempotent. A “set balance to 100” command can be idempotent; “add 10” is not unless it carries a unique operation ID and the server deduplicates repeats. Payment and order APIs commonly use idempotency keys: the server stores the key, request identity, and result for a defined scope/retention window and returns the same result on replay.
The server must handle concurrent duplicates atomically; a check-then-insert race can process the same key twice. Define behavior when a key is reused with a different payload, how long records are retained, and what happens during partial failure. At-least-once message delivery also requires idempotent consumers or deduplication. Exactly-once claims usually rely on scoped transactional/idempotent mechanisms, not transport alone.
Interview questions
- Why is idempotency important for retry? The client may not know if the first attempt committed before the connection failed.
- Is POST inherently non-idempotent? HTTP method semantics suggest behavior, but application endpoints can implement idempotent processing.
- What must an idempotency key system define? Scope, retention, payload mismatch handling, concurrency, and replayed result.
- Is “exactly once” guaranteed by a message broker alone? Usually no; processing side effects need transactional or deduplication design.