Implementing Idempotency Patterns
1. Understanding Idempotent Operations
| HTTP Method | Idempotent | Safe |
|---|---|---|
| GET | Yes | Yes |
| PUT | Yes | No |
| DELETE | Yes | No |
| POST | No (default) | No |
| PATCH | Conditional | No |
2. Implementing Idempotency Keys
Example: Idempotency-Key middleware
@PostMapping("/payments")
public PaymentResponse charge(
@RequestHeader("Idempotency-Key") String key,
@RequestBody PaymentRequest req) {
return idempotencyStore.computeIfAbsent(key,
() -> paymentSvc.execute(req),
Duration.ofHours(24));
}| Property | Detail |
|---|---|
| Key format | Client-generated UUID per logical op |
| Storage TTL | 24h-7d typical (Stripe = 24h) |
| Conflict | Same key, different body → 409 |
3. Implementing Deduplication Strategies
| Strategy | Mechanism |
|---|---|
| Message ID set | Track processed IDs in Redis/RDBMS |
| Bloom filter | Probabilistic, space-efficient |
| Content hash | SHA-256 of payload |
| Sequence numbers | Per-producer monotonic |
| Window-based | Time-bounded dedup window |
4. Handling Retries with Idempotency
| Pattern | Detail |
|---|---|
| Same idempotency key on retry | Server returns cached response |
| Exponential backoff + jitter | Avoid thundering herd |
| Bounded attempts | 3-5 with circuit breaker |
| Distinguish retriable | 5xx/timeouts retry; 4xx do not |
5. Implementing Idempotent APIs
| Technique | Detail |
|---|---|
| Natural keys | Use business id (orderNumber) |
| Conditional headers | If-Match, If-None-Match |
| PUT for create | Client-supplied id |
| Idempotency-Key header | Stripe convention |
6. Understanding Natural vs Artificial Idempotency
7. Implementing Idempotency Token Storage
| Store | Trade-offs |
|---|---|
| Redis (TTL keys) | Fast; eviction risk |
| RDBMS table | Durable; slower |
| DynamoDB TTL items | Managed expiry; cost per op |
| Distributed cache + DB fallback | Hybrid for hot/cold |
8. Handling State Management for Idempotency
| State | Action |
|---|---|
| In progress | Block / return 409 conflict |
| Completed | Return cached result |
| Failed | Allow retry with same key |
| Expired | Treat as new |
9. Implementing Time-Based Deduplication
| Approach | Detail |
|---|---|
| Sliding window | Last N minutes deduped |
| Tumbling window | Per fixed interval |
| Watermark | Drop events older than threshold |
10. Understanding Idempotency Trade-offs
| Pro | Con |
|---|---|
| Safe retries | Storage overhead per request |
| Simpler error handling | TTL boundary edge cases |
| Enables exactly-once semantics | Requires client cooperation |