Idempotency

Idempotency is a property of an operation where applying it multiple times produces the same result as applying it once. Formally: f(f(x)) = f(x).

HTTP methods and idempotency:

Method	Idempotent	Safe	Example
GET	Yes	Yes	Read a resource (no side effects)
PUT	Yes	No	Replace a resource (same result if repeated)
DELETE	Yes	No	Delete a resource (deleting twice = same as once)
HEAD	Yes	Yes	Read headers only
POST	No	No	Create a resource (repeating creates duplicates)
PATCH	No	No	Partial update (depends on implementation)

Making non-idempotent operations safe:

1. Idempotency keys: client generates a unique key (UUID) per request and sends it in a header (Idempotency-Key: abc-123). Server stores the key and result; if the same key arrives again, return the cached result without re-processing.

2. Conditional requests: use If-None-Match (ETag) or If-Unmodified-Since to ensure the operation only executes if the resource state matches expectations.

3. Database constraints: unique constraints prevent duplicate insertions. INSERT ... ON CONFLICT DO NOTHING is idempotent.

Why it matters in distributed systems:

• Network timeouts cause retries (did the server receive my request or not?)
• Message queues may deliver messages more than once (at-least-once delivery)
• Webhooks may fire multiple times for the same event
• Without idempotency, retries cause duplicate charges, duplicate records, or inconsistent state

// API endpoint with idempotency key
app.post("/api/payments", async (req, res) => {
  const idempotencyKey = req.headers["idempotency-key"];
  if (!idempotencyKey) {
    return res.status(400).json({ error: "Idempotency-Key header required" });
  }

  // Check if we already processed this request
  const existing = await db.query(
    "SELECT result FROM idempotency_store WHERE key = $1",
    [idempotencyKey]
  );

  if (existing.rows.length > 0) {
    // Return cached result (safe retry)
    return res.status(200).json(existing.rows[0].result);
  }

  // Process the payment
  const result = await processPayment(req.body);

  // Store the result for future retries
  await db.query(
    "INSERT INTO idempotency_store (key, result, created_at) VALUES ($1, $2, NOW())",
    [idempotencyKey, result]
  );

  return res.status(201).json(result);
});

# Client: safe retry with idempotency key
$ IDEM_KEY=$(uuidgen)
$ curl -X POST https://api.example.com/payments \
  -H "Idempotency-Key: $IDEM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100, "currency": "USD"}'
# Safe to retry with the same key if timeout occurs