API Idempotency Keys & Versioning

A client sends POST /payments to charge $100. The response times out. The client retries. Your API charges $200. This is the fundamental problem that idempotency keys solve: making retries safe. API versioning solves a different but equally important problem: evolving your API without breaking existing clients.

Idempotency Keys

An idempotency key is a client-generated unique identifier (typically a UUID) sent with a request. The server uses it to detect duplicates: if a request with the same key has already been processed, the server returns the cached response without re-executing the operation.

sequenceDiagram
    participant C as Client
    participant S as Server
    participant DB as Database
    participant Cache as Idempotency Store

    C->>S: POST /payments {amount: 100}
Idempotency-Key: abc-123
    S->>Cache: Lookup abc-123
    Cache-->>S: Not found
    S->>DB: INSERT payment (amount=100)
    S->>Cache: Store abc-123 → {status: 200, body: {id: 42}}
    S->>C: 200 OK {id: 42}

    Note over C,S: Network timeout — client retries

    C->>S: POST /payments {amount: 100}
Idempotency-Key: abc-123
    S->>Cache: Lookup abc-123
    Cache-->>S: Found → {status: 200, body: {id: 42}}
    S->>C: 200 OK {id: 42} (cached — no duplicate charge)

Server-Side Implementation

def handle_payment(request):
    idempotency_key = request.headers.get("Idempotency-Key")
    if not idempotency_key:
        return error(400, "Idempotency-Key header required")

    result_key = f"idem:{idempotency_key}"
    lock_key = f"idem_lock:{idempotency_key}"

    # Fast path: a previous call already completed — return its result.
    cached = redis.get(result_key)
    if cached:
        return json.loads(cached)

    # Acquire a short-lived lock to serialize concurrent duplicates.
    if not redis.set(lock_key, "1", nx=True, ex=30):
        return error(409, "Request in progress — retry later")

    try:
        # Re-check the cache: another caller may have completed between
        # our initial miss and our lock acquisition.
        cached = redis.get(result_key)
        if cached:
            return json.loads(cached)

        result = process_payment(request.body)

        # Cache the response with a long TTL so future retries are idempotent.
        redis.setex(
            result_key,
            86400,  # 24 hour TTL
            json.dumps({"status": 200, "body": result}),
        )
        return success(result)
    finally:
        # Always release the lock — on success, on error, and on early return.
        redis.delete(lock_key)

Storage for Idempotency Keys

Stripe’s approach: stores idempotency keys in their database within the same transaction as the payment. The payment insert and idempotency record are atomic — no window for inconsistency.

Key Design Decisions

Who generates the key? The client — always. The server cannot generate a meaningful idempotency key because it doesn’t know which client retries map to which original request.

Key scope: one key per logical operation. If the client retries with the same key but a different request body, the server should return an error (not silently use the cached result or re-execute with new parameters).

TTL: 24 hours is typical. Too short and delayed retries fail. Too long and storage grows indefinitely.

API Versioning

APIs evolve. Fields get added, renamed, or removed. Response formats change. Without versioning, any change risks breaking existing clients — and you can’t force all clients to upgrade simultaneously.

Versioning Strategies

URL path versioning dominates in practice. Stripe (/v1/), GitHub (/v3/), Twilio (/2010-04-01/) all use URL-based versioning because it’s explicit and hard to miss.

Breaking vs Non-Breaking Changes

Rule of thumb: you can always add optional things. You can never remove, rename, or change the type of existing things without a version bump.

Sunset and Deprecation

When you release v2, v1 doesn’t disappear overnight. A deprecation lifecycle:

v1 released: 2024-01-01
v2 released: 2025-01-01
v1 deprecated: 2025-01-01 (announced, still works)
v1 sunset: 2025-07-01 (returns 410 Gone)

Timeline:
|------ v1 active ------|-- v1 deprecated --|-- v1 gone --|
                         |------------- v2 active ----------|

Response headers for deprecation:

HTTP/1.1 200 OK
Sunset: Sat, 01 Jul 2025 00:00:00 GMT
Deprecation: true
Link: <https://api.example.com/docs/migration-v2>; rel="deprecation"

Monitoring: track the percentage of traffic still hitting deprecated versions. If 30% of traffic is on v1 three months before sunset, send targeted migration reminders or extend the grace period.

Date-Based Versioning

An alternative to incremental version numbers: use the API release date as the version identifier.

Stripe: API-Version: 2024-12-18
Twilio: /2010-04-01/Accounts/...

Advantage: finer granularity — each API release date is a version. Clients pin to the date they integrated, and new changes are introduced under newer dates. The server maintains backward compatibility for all pinned dates within the support window.

Comparison: Idempotency vs Versioning

Test Your Understanding