What Is Idempotent in REST API Design?

// Node.js 20: client-side retry without idempotency protection
async function chargeCustomer(amount, customerId) {
  for (let attempt = 1; attempt <= 3; attempt++) {
    try {
      const response = await fetch("/api/charges", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ amount, customer_id: customerId }),
      });
      return await response.json();
    } catch (err) {
      if (attempt === 3) throw err;
      await new Promise((r) => setTimeout(r, attempt * 1000));
    }
  }
}

CREATE TABLE idempotency_keys (
  id              BIGSERIAL PRIMARY KEY,
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
  idempotency_key TEXT NOT NULL,
  last_run_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
  locked_at       TIMESTAMPTZ,
  recovery_point  TEXT NOT NULL DEFAULT 'started',
  request_method  TEXT NOT NULL,
  request_path    TEXT NOT NULL,
  request_params  JSONB NOT NULL,
  response_code   INT,
  response_body   JSONB,
  user_id         BIGINT NOT NULL,
  expires_at      TIMESTAMPTZ NOT NULL DEFAULT (now() + INTERVAL '24 hours'),
  UNIQUE(user_id, idempotency_key)
);
 
CREATE INDEX ON idempotency_keys (expires_at);

// Node.js 20: PostgreSQL idempotency key store (pg@8)
import pg from "pg";
import { isDeepStrictEqual } from "node:util";
const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
 
export async function acquireIdempotencyKey(userId, key, method, path, params) {
  const client = await pool.connect();
  try {
    await client.query("BEGIN");
    const requestParams = params ?? {};
 
    const insert = await client.query(
      `INSERT INTO idempotency_keys
         (user_id, idempotency_key, request_method, request_path, request_params)
       VALUES ($1, $2, $3, $4, $5)
       ON CONFLICT (user_id, idempotency_key) DO NOTHING
       RETURNING *`,
      [userId, key, method, path, JSON.stringify(requestParams)],
    );
 
    if (insert.rows.length > 0) {
      // We inserted; we own this request
      await client.query("COMMIT");
      return { status: "new", record: insert.rows[0] };
    }
 
    // Key already exists; fetch it with a lock
    const existing = await client.query(
      `SELECT * FROM idempotency_keys
       WHERE user_id = $1 AND idempotency_key = $2
       FOR UPDATE NOWAIT`,
      [userId, key],
    );
 
    await client.query("COMMIT");
    const record = existing.rows[0];
 
    // Params mismatch; reject
    if (!isDeepStrictEqual(record.request_params, requestParams)) {
      return { status: "conflict" };
    }
 
    // Already completed; return cached response
    if (record.response_code !== null) {
      return { status: "cached", record };
    }
 
    // In-flight; signal the client to retry
    return { status: "in_progress" };
  } catch (err) {
    await client.query("ROLLBACK");
    // FOR UPDATE NOWAIT throws 55P03 if the row is already locked
    if (err.code === "55P03") {
      return { status: "in_progress" };
    }
    throw err;
  } finally {
    client.release();
  }
}
 
export async function completeIdempotencyKey(
  userId,
  key,
  responseCode,
  responseBody,
) {
  await pool.query(
    `UPDATE idempotency_keys
     SET response_code = $3,
         response_body = $4,
         recovery_point = 'completed',
         last_run_at    = now()
     WHERE user_id = $1 AND idempotency_key = $2`,
    [userId, key, responseCode, JSON.stringify(responseBody)],
  );
}

// Node.js 20: Express idempotency middleware
import {
  acquireIdempotencyKey,
  completeIdempotencyKey,
} from "../db/idempotency.js";
 
const UUID_V4 =
  /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
export function idempotencyMiddleware() {
  return async (req, res, next) => {
    const key = req.headers["idempotency-key"];
 
    // Idempotency is opt-in; skip if no key
    if (!key) return next();
 
    if (!UUID_V4.test(key)) {
      return res.status(400).json({
        error: "invalid_idempotency_key",
        message: "Idempotency-Key must be a valid UUID v4.",
      });
    }
 
    const userId = req.user?.id;
    if (!userId) {
      return res.status(401).json({
        error: "unauthorized",
        message: "Authentication is required before idempotency checks.",
      });
    }
 
    const result = await acquireIdempotencyKey(
      userId,
      key,
      req.method,
      req.path,
      req.body,
    );
 
    switch (result.status) {
      case "cached":
        return res
          .status(result.record.response_code)
          .json(result.record.response_body);
 
      case "conflict":
        return res.status(400).json({
          error: "idempotency_key_reuse",
          message: "This key was used with different request parameters.",
        });
 
      case "in_progress":
        return res.status(409).json({
          error: "request_in_progress",
          message:
            "A request with this key is already being processed. Retry shortly.",
        });
 
      case "new": {
        // Intercept res.json to capture the response for storage (sync override; persistence is fire-and-forget)
        const originalJson = res.json.bind(res);
        res.json = (body) => {
          completeIdempotencyKey(userId, key, res.statusCode, body).catch(
            (err) => {
              console.error("Idempotency completion failed:", err);
            },
          );
          return originalJson(body);
        };
        return next();
      }
    }
  };
}

// Node.js 20: Express charge route with layered idempotency
import express from "express";
import Stripe from "stripe";
import { idempotencyMiddleware } from "../middleware/idempotency.js";
 
const router = express.Router();
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
 
router.post("/charges", idempotencyMiddleware(), async (req, res) => {
  const { amount, currency, payment_method_id } = req.body;
 
  const paymentIntent = await stripe.paymentIntents.create(
    { amount, currency, payment_method: payment_method_id, confirm: true },
    // Pass your key to Stripe as a second layer of deduplication
    { idempotencyKey: req.headers["idempotency-key"] },
  );
 
  res.status(201).json({
    id: paymentIntent.id,
    status: paymentIntent.status,
    amount: paymentIntent.amount,
  });
});
 
export default router;

// Node.js 20 built-in test runner
import { describe, it } from "node:test";
import assert from "node:assert/strict";
import crypto from "node:crypto";
 
const BASE_URL = "http://localhost:3000";
 
async function charge(idempotencyKey, amount = 4999) {
  const res = await fetch(`${BASE_URL}/charges`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.TEST_TOKEN}`,
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify({
      amount,
      currency: "usd",
      payment_method_id: "pm_card_visa", // Stripe test payment method
    }),
  });
  return { status: res.status, body: await res.json() };
}
 
describe("Idempotency middleware", () => {
  it("returns the same charge ID for duplicate keys", async () => {
    const key = crypto.randomUUID();
    const first = await charge(key);
    const second = await charge(key);
 
    assert.equal(first.status, 201);
    assert.equal(second.status, 201);
    assert.equal(first.body.id, second.body.id); // same charge, not a new one
  });
 
  it("returns 409 for concurrent duplicate requests, exactly one succeeds", async () => {
    const key = crypto.randomUUID();
    const results = await Promise.all([charge(key), charge(key), charge(key)]);
 
    const successes = results.filter((r) => r.status === 201);
    const conflicts = results.filter((r) => r.status === 409);
 
    assert.equal(successes.length, 1);
    assert.ok(conflicts.length >= 1);
    // All successful responses reference the same charge
    assert.equal(new Set(successes.map((r) => r.body.id)).size, 1);
  });
 
  it("returns 400 for parameter mismatch on same key", async () => {
    const key = crypto.randomUUID();
    await charge(key, 4999); // establish the key
    const mismatch = await charge(key, 9999); // different amount
 
    assert.equal(mismatch.status, 400);
    assert.equal(mismatch.body.error, "idempotency_key_reuse");
  });
});