idempotency-patterns

# Idempotency Patterns

Patterns for designing APIs and systems that handle retries safely without duplicate side effects.

## When to Use This Skill

- Designing APIs that handle retries safely
- Implementing idempotency keys
- Preventing duplicate operations
- Building reliable payment/order systems
- Handling network failures gracefully

## What is Idempotency?

```text
Idempotent operation: Same result regardless of how many times executed

f(x) = f(f(x)) = f(f(f(x))) = ...

Examples:
- GET /user/123      → Always returns same user (idempotent)
- DELETE /user/123   → User deleted once, subsequent calls no-op (idempotent)
- POST /orders       → Creates new order each time (NOT idempotent)
```

## Why Idempotency Matters

```text
Network reality:
Client ──request──> Server
       <──response── (lost!)

Client doesn't know if request succeeded.
Should it retry?

Without idempotency:
- Retry creates duplicate order
- Customer charged twice
- Inventory decremented twice

With idempotency:
- Retry returns same result
- No duplicate side effects
- Safe to retry
```

## HTTP Method Idempotency

| Method | Idempotent | Safe | Notes |
| ------ | ---------- | ---- | ----- |
| GET | Yes | Yes | No side effects |
| HEAD | Yes | Yes | No side effects |
| OPTIONS | Yes | Yes | No side effects |
| PUT | Yes | No | Replace entire resource |
| DELETE | Yes | No | Delete is idempotent (already deleted = no-op) |
| POST | No | No | Creates new resource |
| PATCH | Maybe | No | Depends on implementation |

## Idempotency Key Pattern

### Concept

```text
Client generates unique key, server tracks processed keys

Request 1:
POST /payments
Idempotency-Key: abc-123
{amount: 100}
→ Process payment, store result with key abc-123

Request 2 (retry):
POST /payments
Idempotency-Key: abc-123
{amount: 100}
→ Find stored result for abc-123, return same response
→ No duplicate payment
```

### Implementation

```text
Idempotency store schema:
┌──────────────────────────────────────────────────┐