Idempotency in RESTful APIs
What you'll learn: How to design APIs where repeated identical requests produce the same result, ensuring safe retries and predictable behavior.
What Is Idempotency?
Idempotency means that making the same request multiple times has the same effect as making it once. If a client sends a request but doesn't receive a response due to network issues, they should be able to safely retry without causing duplicate side effects or unexpected state changes.
Think of it like pressing an elevator button: whether you press the "up" button once or ten times, the elevator still comes once.
HTTP Methods and Idempotency
GET is naturally idempotent—reading data multiple times doesn't change anything.
PUT must be idempotent. When you update a resource at /users/123 with {"name": "Alice"}, sending that request twice results in the same final state: the user's name is "Alice." You're defining the complete state, not adding to it.
DELETE should be idempotent. Deleting /users/123 the first time removes the resource. Deleting it again (receiving a 404 or 204) doesn't cause additional harm—the end state is identical: the resource is gone.
POST is not inherently idempotent. Creating a resource at /users might generate a new ID each time. Two identical POST requests could create two users.
Making POST Idempotent
To handle retries safely for POST:
- Accept an idempotency key in request headers (e.g.,
Idempotency-Key: abc-123) - Store this key with the operation result
- On retry with the same key, return the original response instead of creating duplicates
This prevents double-charging a credit card or creating duplicate orders when clients retry failed requests.
Key Takeaway: Design PUT and DELETE to always produce the same outcome regardless of repetition, and use idempotency keys to make POST requests safely retryable without side effects.