Was ist Idempotenz? HTTP-Methoden, API-Keys, Beispiele

Was ist Idempotenz?

Idempotenz ist eine Eigenschaft einer Operation, bei der die mehrfache Ausführung dasselbe Ergebnis produziert wie die einmalige Ausführung. Mathematisch: f(x) = f(f(x)) = f(f(f(x))). In API- und verteilten Systemen-Kontexten kann eine idempotente Operation sicher wiederholt werden ohne unbeabsichtigte Nebenwirkungen, kritisch wenn Netzwerke unzuverlässig sind und Sie nicht wissen, ob Ihr vorheriger Request erfolgreich war.

Das klassische Beispiel ist ein Aufzugsknopf: einmal drücken oder zehnmal drücken produziert dasselbe Ergebnis (der Aufzug kommt einmal). Vergleichen Sie mit dem Belasten einer Kreditkarte: zehnmal "Bezahlen" drücken ohne Idempotenz produziert zehn Belastungen. Idempotenz-Design macht Systeme sicher zu retry'en.

Idempotenz in HTTP/REST APIs

Die HTTP-Spezifikation (RFC 7231) definiert, welche Methoden idempotent sind:

Beachten Sie: idempotent bedeutet NICHT "dieselbe Response zurückgeben". DELETE returnt 204 beim ersten Mal und 404 bei nachfolgenden Calls, verschiedene Responses, aber der Server-State ist identisch. Die Eigenschaft betrifft den End-State, nicht Response-Equivalenz.

Beispiele: idempotent vs nicht-idempotent

Idempotente Operationen

• PUT /users/123 {"name": "Alice"}, setzt den User-Namen auf Alice. 10x aufgerufen lässt den Namen Alice.
• DELETE /sessions/abc, entfernt Session abc. 10x aufgerufen resultiert weiterhin in keiner Session abc.
• GET /products/42, liest Produkt 42.
• PUT /flags/feature-x {"enabled": true}. Feature-Flag-Toggle nach Absolutwert.

Nicht-idempotente Operationen

• POST /orders {...}, erstellt eine neue Order. 10x aufgerufen erstellt 10 Orders.
• POST /charges {...}, belastet eine Kreditkarte. 10x aufgerufen belastet 10x.
• PATCH /counters/x {"increment": 1}, inkrementiert um 1 bei jedem Call.
• POST /emails {"to": "..."}, sendet eine E-Mail. 10 Calls = 10 E-Mails.

Warum Idempotenz wichtig ist

In einer Single-Machine-Transactional-Welt würden Sie nie dieselbe Operation zweimal aufrufen. Aber moderne Systeme sind verteilt, und das ändert alles:

• Netzwerk-Fehler. Ihr Client sendet einen Request, bekommt keine Response. Erfolgreich? Sie wissen es nicht. Idempotent → sicher retry'en.
• Timeouts. Selbes Problem. Der Server kann den Request verarbeitet haben nachdem der Client aufgegeben hat.
• Verteilte Retries. Service Meshes, Load Balancers und SDKs retry'en auto. Sicher nur wenn upstream idempotent.
• Queue-basierte Architekturen. Messages können mehr als einmal geliefert werden (at-least-once). Consumers müssen Duplikate idempotent handhaben.
• Nutzer-Verhalten. Nutzer doppelklicken Submit-Buttons, refresh'en Pages mitten im Request.

Idempotenz-Keys

Für natürlich nicht-idempotente Operationen wie Order-Erstellung oder Karten-Belastung ist das Standard-Pattern der Idempotenz-Key: ein client-generierter eindeutiger Identifier (typischerweise UUID), gesendet mit jedem Request. Der Server speichert das Ergebnis nach diesem ID und returnt dasselbe Ergebnis bei nachfolgenden Requests mit demselben Key.

POST /charges
Idempotency-Key: 8e0a4e6b-1b8e-4e3a-b9f7-5e1d3f9c4b8a
{
  "amount": 5000,
  "currency": "USD"
}

Der erste Call verarbeitet die Belastung und speichert das Ergebnis. Nachfolgende Calls mit demselben Key returnen das gespeicherte Ergebnis ohne Re-Processing. Der Key läuft typischerweise nach einem Window ab (z.B. 24 Stunden).

Idempotenz-Keys server-seitig implementieren

1. Request mit Idempotenz-Key empfangen.
2. Key-Store (Redis, DB-Tabelle) auf existierenden Eintrag prüfen.
3. Wenn gefunden: gespeicherte Response returnen (keine Side-Effects).
4. Wenn nicht gefunden: Lock auf Key acquiren, Request verarbeiten, Response speichern, Lock releasen.
5. In-Flight-Requests handhaben: wenn ein Duplikat ankommt während der erste verarbeitet wird, entweder warten oder 409 Conflict returnen.
6. Keys nach dem vereinbarten Window expiren.

Real-World-Beispiele

• Stripe. Die Referenz-Implementierung. Jeder state-ändernde API-Endpoint akzeptiert einen Idempotency-Key-Header.
• AWS SDK. Viele AWS-APIs nutzen ClientToken-Parameter (Idempotenz-Keys). EC2 RunInstances, RDS CreateDBInstance.
• PayPal, Square, Adyen. Alle Payment-Processors nutzen Idempotenz-Keys.
• HTTP/2 + retry-aware Clients. Moderne HTTP-Clients retry'en automatisch idempotente Methoden bei Connection-Failures.

Häufige Fallstricke

• PATCH als immer idempotent behandeln. Hängt von Semantik ab.
• Side-Effects jenseits der Datenbank. Wenn Ihr "idempotenter" Endpoint eine E-Mail sendet, sendet zweimaliges Aufrufen zwei E-Mails.
• Idempotenz-Keys ohne Expiry. Jeden Key forever zu speichern verursacht unbegrenztes Wachstum. TTLs setzen.
• Race Conditions bei konkurrierenden Retries. Locks oder Database-Constraints nutzen.
• Idempotenz mit Safety verwechseln. Safe = keine Side-Effects (GET). Idempotent = N Calls = 1 Call's Effect. PUT/DELETE sind idempotent aber nicht safe.

Idempotenz in Load Testing

• POST-Endpoints akkumulieren State. Ein 1.000-VU-Lasttest gegen POST /orders erstellt 1.000 × Duration × RPS Orders. Cleanup danach.
• Idempotenz-Key-Reuse cached die Response. Wenn Ihr Script denselben Key über VUs reuse't, bekommen alle VUs die gecachte erste Response.
• Eindeutige Idempotenz-Keys pro VU/Iteration generieren.
• Den Idempotenz-Mechanismus selbst testen.

FAQ: Idempotenz

Ist GET immer idempotent?

Per HTTP-Spec ja. GET sollte nie State modifizieren. In der Praxis missbrauchen manche APIs GET für State-Änderungen.

Ist PATCH idempotent?

Hängt von der Operation ab. PATCH {set: x} ist idempotent. PATCH {increment: 1} nicht.

Was ist der Unterschied zwischen Idempotenz und Safety?

Safe bedeutet keine beobachtbaren Side-Effects (GET, HEAD, OPTIONS). Idempotent bedeutet N Calls = 1 Call's End-State. PUT und DELETE sind idempotent aber nicht safe.

Wie mache ich POST idempotent?

Idempotenz-Key nutzen, eine client-generierte UUID gesendet mit jedem Request.

Was ist eine gute Idempotenz-Key-TTL?

Stripe nutzt 24 Stunden. Für high-throughput APIs reicht 1 Stunde. Für Payment-APIs gibt 7-30 Tage mehr Retry-Toleranz.

Gilt Idempotenz für gRPC und GraphQL?

Ja. gRPC-Method-Definitionen können Idempotenz-Level spezifizieren. GraphQL Query-Operations sind idempotent per Konvention; Mutations brauchen explizites Idempotenz-Design.

Probieren Sie LoadFocus für Idempotenz-Testing at Scale

Wenn Sie einen Idempotenz-Mechanismus designen und unter Last verifizieren wollen (konkurrierende Retries, Race Conditions, Key-Expiry), läuft LoadFocus JMeter- und k6-Scripts aus 25+ Cloud-Regionen mit bis zu 12.500 VUs. Registrieren bei loadfocus.com/signup, keine Kreditkarte, und führen Sie Ihren ersten Idempotenz-Stresstest in unter 5 Minuten aus.