idempotency

Idempotency Best Practices

This skill provides idempotency concepts, patterns, and implementation strategies applicable across multiple programming languages and frameworks.

Core Concepts

What is Idempotency?

An operation is idempotent if performing it multiple times produces the same result as performing it once.

Mathematical Example:

• f(f(x)) = f(x)
• Example: abs(abs(-5)) = abs(-5) = 5

Programming Example:

• GET request: Always returns same result
• DELETE request: Deleting twice has same effect as once
• PUT request: Replacing resource multiple times has same effect

Why Idempotency Matters

1. Retry Safety: Network failures can cause retries - operations must handle this
2. Distributed Systems: Multiple services may attempt same operation
3. User Experience: Users may click "Submit" multiple times
4. Reliability: Ensures system consistency under failures

HTTP Methods and Idempotency

Idempotent Methods

GET: Always safe and idempotent

• Reading data doesn't change state
• Can be called multiple times safely

PUT: Idempotent (when used correctly)

• Replacing resource with same data multiple times has same effect
• Must include complete resource representation

DELETE: Idempotent

• Deleting already-deleted resource has same effect (no-op)

Non-Idempotent Methods

POST: Not idempotent

• Creates new resources
• Each call may create different resource

PATCH: Not idempotent (usually)

• Partial updates may have different effects on repeated calls

API Idempotency Patterns

Pattern 1: Idempotency Keys

Client provides unique key for each operation. Server uses key to detect duplicates.

// Client sends request with idempotency key
POST /api/orders
Headers:
  Idempotency-Key: abc123-def456-ghi789

// Server implementation
const idempotencyKey = req.headers['idempotency-key'];

if (idempotencyKey) {
  // Check if we've seen this key before
  const cachedResponse = await cache.get(`idempotency:${idempotencyKey}`);
  if (cachedResponse) {
    return res.status(cachedResponse.status).json(cachedResponse.body);
  }
  
  // Process request
  const order = await createOrder(req.body);
  
  // Cache response
  await cache.set(`idempotency:${idempotencyKey}`, {
    status: 201,
    body: order,
  }, { ttl: 24 * 60 * 60 }); // 24 hours
  
  return res.status(201).json(order);
}