Course contentsShow
← System Design
Lesson 1884 of 1,91945. API Design and VersioningFree lesson

Idempotency in RESTful APIs

Ensuring PUT and DELETE are idempotent and handling retries safely for POST requests.

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.