Course contentsShow
← System Design
Lesson 1008 of 1,91926. Idempotency and RetriesFree lesson

What Makes an API Idempotent

Define idempotency for APIs: multiple identical requests produce the same result and side effects as a single request.

What Makes an API Idempotent

You'll learn: The specific characteristics that make an API endpoint truly idempotent, distinguishing safe operations from those requiring careful design.

Core Idea

An API is idempotent when calling it multiple times with identical requests produces the same result and same side effects as calling it exactly once. Notice both parts matter: the response and what changes in your system.

Think of a light switch labeled "Turn On." No matter how many times you flip it when it's already on, the light stays on—that's idempotency. The state (light on) and the outcome (room illuminated) remain unchanged after the first successful flip.

What Makes It Idempotent

For an API to be idempotent:

  1. Same request parameters → Same final system state
  2. Side effects happen once (database writes, external API calls, charges)
  3. Safe to retry without fear of duplication
  4. Result consistency across retries (may return same response or updated metadata)

Examples

Idempotent: PUT /users/123 with {"name": "Alice"} — sets the name to Alice. Call it 5 times, name is still Alice, written once or overwritten with identical value.

Idempotent: DELETE /users/123 — deletes user 123. Second call finds user already deleted; final state is the same (user gone).

Not idempotent: POST /users creating a new user without idempotency keys — each call creates a duplicate user with a new ID.

Not idempotent (naturally): POST /wallet/charge for 10—eachretrychargesanother10 — each retry charges another 10.

The last example can be made idempotent using idempotency keys and server-side deduplication, which you've already learned about.

Key Takeaway: An API is idempotent when multiple identical requests produce the same system state and side effects as one request—the operation can be safely retried without unintended duplication.