API design
Idempotent HTTP methods: interview questions and practical design
An HTTP method is idempotent when repeating the same request has the same intended server effect as sending it once, even though responses may differ.
Written and reviewed by Sahil Srivastav
What it actually is
An HTTP method is idempotent when repeating the same request has the same intended server effect as sending it once, even though responses may differ.
Retries are unavoidable after a lost response. Method semantics let clients and intermediaries reason about which retries are safe.
The useful interview answer is precise about the boundary: Idempotency concerns the requested effect, not identical response bytes. A first PUT can return 200 and a repeat 204 while both leave the resource in the same state.
Why it matters in production
Retries are unavoidable after a lost response. Method semantics let clients and intermediaries reason about which retries are safe.
Verb names do not enforce behaviour: a GET with a hidden mutation or a PUT that appends data violates the contract and creates duplicate effects.
How it works
Effect versus response
Idempotency concerns the requested effect, not identical response bytes. A first PUT can return 200 and a repeat 204 while both leave the resource in the same state.
PUT and absolute state
PUT identifies the target and supplies its desired representation. It is naturally idempotent when the server replaces that representation rather than applying a relative update.
POST and explicit keys
POST usually creates a new subordinate resource each time. When a client must retry it safely, an idempotency key binds attempts to one logical operation and stores the original result.
Implementing it
Classify every mutation in a small API as absolute assignment, guarded transition, append, or relative update.
Send duplicate requests concurrently and assert one durable effect.
Document which failures are safe to retry and who supplies the deadline.
Interview questions and how to answer them
Is DELETE idempotent?
A DELETE of the same resource is intended to converge: the first removes it and later calls observe absence. The API still needs a clear response and must avoid deleting a newly recreated resource through an unsafe identity scheme.
Can POST be idempotent?
Yes. Store a client key under a uniqueness constraint, claim it atomically with the creation, and return the stored response for later attempts.
Why does idempotency matter after a timeout?
The client cannot know whether the server committed before the connection failed. A repeatable effect lets it retry without turning uncertainty into a duplicate.
Answers that lose the round
- Saying POST is never idempotent or PUT is always idempotent without examining the handler.
- Using a request hash as an idempotency key when two valid identical operations must both happen.
- Returning a duplicate error instead of the original result for a retried command.
- Making GET trigger a write such as an audit or lazy initialisation.
FAQ
Does idempotent mean side-effect free?
No. A PUT can write logs or update a last-seen timestamp while remaining idempotent with respect to the resource state; define which effect the contract covers.
Are safe methods also idempotent?
Safe methods are intended to be read-only and are therefore idempotent in their resource effect, but a server must not add hidden mutations that violate that expectation.
How should I test idempotency?
Repeat the same request after success, after a lost response, and concurrently. Assert the final state and externally visible side effects.