What Is API Idempotency and How Do You Design Idempotent APIs?

API Idempotency

Definition

Executing the same operation multiple times produces the same result as executing it once.

HTTP Method Idempotency

Method	Idempotent	Safe (no side effects)
GET	Yes	Yes
PUT	Yes	No
DELETE	Yes	No
POST	No	No
PATCH	No (usually)	No

Why It Matters

• On network instability, clients may retry and cause duplicate operations (e.g., double charges)
• Idempotent design makes retries safe

Implementation: Idempotency Key

1. Client generates a unique key (e.g., UUID)
2. Sends in header: Idempotency-Key: <uuid>
3. Server stores result indexed by this key (Redis / DB)
4. Duplicate requests with same key return cached result

Storage Strategy

• Redis (24h TTL): store key → response mapping
• Use SET NX (SET if Not eXists) for atomicity to prevent race conditions