Idempotenz Regeln – HTTP, REST API, Idempotency Key & ETag

Dieser Beitrag ist eine Begriffserklärung zu Idempotenz – inklusive Prüfungsfragen und Tags.

In a Nutshell

Idempotenz bedeutet: identische Operation beliebig oft mit gleichem Ergebnis ausführen. Formal: f(f(x)) = f(x).

Kompakte Fachbeschreibung

Idempotenz ist eine Eigenschaft einer Operation, nicht eines Endpunkts. Sie macht das Resultat gegenüber Wiederholungen stabil. In HTTP sind GET, HEAD, PUT, DELETE per Spezifikation idempotent, POST ist es nicht, kann aber durch Idempotency Key idempotent gestaltet werden. Praktisch bedeutet Idempotenz, dass Wiederholungen keinen zusätzlichen Seiteneffekt erzeugen (keine doppelten Bestellungen, kein mehrfaches Abbuchen). Technisch erreicht man dies durch deterministische Zustandsübergänge, Versionsprüfungen mit ETag und deduplizierende Serverlogik. In verteilten Systemen mit mindestens einmal Zustellung sind Retries normal, Idempotenz macht sie sicher.

Prüfungsrelevante Stichpunkte

• Definition: f(f(x)) = f(x), Idempotenz als Eigenschaft der Operation, nicht des Pfads
• HTTP Zuordnung: GET/HEAD sicher und idempotent, PUT/DELETE idempotent, POST nicht idempotent
• POST-Idempotenz mit Idempotency Key, Request-Hash, deduplizierendem Store, deterministischen Antworten
• Status und Header: 201 mit Location beim Erstversuch, Wiederholung liefert 200/201 konsistent, 412 bei If-Match Konflikt
• Nachvollziehbarkeit der Nebenwirkungen, Protokollierung der Korrelations-ID, dokumentierte Retry-Regeln
• Keine sensiblen Daten in Fehlern, Schutz vor Replay durch zeitlich begrenzte Keys und Signaturen
• Weniger Doppelbuchungen und Supportfälle, robuste Integrationen, klar definierte Retry-Politik
• OpenAPI beschreibt Idempotenz, Fehlerkatalog, Lebensdauer der Idempotency Keys, Beispielantworten

Kernkomponenten

1. Formale Definition und Abgrenzung zu Safe-Eigenschaften
2. Methodensemantik in HTTP: GET, HEAD, PUT, PATCH, DELETE, POST
3. Bedingte Requests mit ETag, If-Match, If-None-Match
4. Deduplizierung: Speicher, Key zu Response, Mapping mit Ablaufzeit
5. Deterministische Zustandsübergänge und Konflikterkennung (409, 412)
6. Idempotency Key Generierung: Client erzeugt stabilen Schlüssel pro Geschäftsvorfall
7. Outbox/Inbox Pattern für zuverlässige Nebenwirkungen (Events, Zahlungen)
8. Retry-Strategie: exponentielles Backoff, 429 und Retry-After respektieren
9. Beobachtbarkeit: Korrelations-ID, idempotente Operationen nachvollziehen
10. Testverfahren: Wiederholungs-Tests, Chaos-Tests, Parallelitäts- und Race-Tests

Praxisbeispiel

// Idempotentes POST für Zahlung mit Idempotency Key und ETag
POST payments
Headers: Content-Type: application/json, Idempotency-Key: pay-123-abc
Body: { orderId: 42, amount: 59.98, method: "card" }

Serverlogik:
if exists DedupeStore[key: pay-123-abc]:
    return storedResponse
else:
    if PaymentAlreadyConfirmed(orderId: 42):
        resp = { id: "P9001", status: "confirmed" }, code: 200
    else:
        create Payment(id: "P9001", status: "confirmed")
        resp = { id: "P9001", status: "confirmed" }, code: 201, headers: ETag: W/"r77"
    DedupeStore.save(key: pay-123-abc -> resp with ttl: 24h)
    return resp

Wiederholung mit gleichem Key:
Client sendet erneut POST mit Idempotency Key, Server liefert dieselbe Antwort, 201 beim Erstversuch, 200 bei späteren Wiederholungen, niemals doppelte Abbuchung.

Vorteile und Nachteile

Vorteile

• Sichere Retries bei Netzfehlern
• Schutz vor Doppelbuchungen
• Klarere Fehlermodellierung
• Robustere Integrationen
• Bessere Nutzererfahrung

Nachteile

• Zusätzlicher Speicher und Verwaltungsaufwand für Deduplizierung
• Komplexere Logik bei Nebenwirkungen
• Genaue Definition der Lebensdauer und Semantik notwendig
• Mögliche Sperren oder Konflikte bei Parallelität

Typische Prüfungsfragen (mit Kurzantwort)

1. Unterschied Safe vs. Idempotent? Safe = keine serverseitige Zustandsänderung (GET), Idempotent = Mehrfachausführung ohne zusätzliche Nebenwirkungen (PUT/DELETE).
2. POST Operationen idempotent machen? Idempotency Key pro Geschäftsvorfall, Deduplizierungs-Store mit Key→Response, deterministische Logik, konsistente Statuscodes, begrenzte Gültigkeit.
3. ETag und If-Match bei Idempotenz? Schützen vor verlorenen Updates, Update nur bei bekannter Version, sonst 412 Precondition Failed.
4. DELETE wirklich idempotent? Erstes DELETE liefert 200/204, spätere DELETE können 204/404 liefern, Systemzustand bleibt gleich (Ressource gelöscht).
5. Typische Statuscodes bei Idempotenz/Retries? 200/201/204 bei Erfolgen, 409 bei Geschäfts-Konflikten, 412 bei Vorbedingung verletzt, 429 bei Limits + Retry-After, 5xx für temporäre Serverfehler.
6. Lebensdauer Idempotency Key definieren? Fachlich bis Geschäftsvorfall final, technisch als Zeitfenster (z.B. 24h), dokumentiert in API.
7. Risiken ohne Idempotenz in verteilten Systemen? Doppelte Nebenwirkungen (doppelte Zahlungen), inkonsistente Zustände, manuelle Korrekturen, höhere Supportkosten.
8. Idempotenz mit Event Sourcing und Outbox? Ereignis in Outbox schreiben (gleiche Transaktion), zuverlässig publizieren, Konsument mit Inbox für verarbeitete Event-IDs, idempotenter Handler.

Wichtigste Quellen

1. https://www.rfc-editor.org/rfc/rfc9110
2. https://www.rfc-editor.org/rfc/rfc7807
3. https://docs.stripe.com/idempotency