Der Client weist einer Geschäftsoperation einen stabilen Idempotenzschlüssel zu, der Server bindet ihn an Identität und Inhalt der Anfrage, speichert den Zustand atomar und gibt bei einer Wiederholung das ursprüngliche Ergebnis oder einen sicheren Konflikt zurück. Testen Sie das Konzept bei Nebenläufigkeit, Timeouts und teilweisem Ausfall.
API-Idempotenz bedeutet, dass die wiederholte Ausführung derselben beabsichtigten Operation keine weitere unerwünschte Wirkung erzeugt. Sie ist wichtig bei Bestellungen, Zahlungen, Rechnungen, Reservierungen oder dem Import von Kontakten. Ein Client kann eine Anfrage nach einem Timeout wiederholen, ein Nutzer zweimal klicken und ein Vermittler ein Ereignis mehrfach zustellen, obwohl der erste Versuch bereits erfolgreich war.
Eine einfache Prüfung, ob ein Datensatz existiert, reicht bei gleichzeitigen Zugriffen oder Teilausfällen möglicherweise nicht aus. Der Entwurf benötigt eine Identität der Operation, eine atomare Speicherung des Status, Regeln für wiederholte Antworten und eine sichere Korrektur. Idempotenz bedeutet nicht, jede ähnliche Anfrage zu ignorieren; zwei tatsächlich unterschiedliche Bestellungen müssen unterschiedlich bleiben.
Praxisbeispiel: einen Batch ohne doppelten Schreibvorgang wiederholen
Bei Massenänderungen an unserer eigenen Website arbeiten wir mit 200 Artikeln. Der Vorgang muss daher nach einer Unterbrechung fortgesetzt werden können und bereits verarbeitete Artikel erkennen. Grundlage sind eine stabile Identität des Datensatzes, ein gespeicherter Plan und eine Prüfung des aktuellen Zustands vor dem Schreiben. Dieselbe Entscheidungslogik ist auch bei einer API-Integration von Bestellungen nötig.
Das folgende Beispiel ist ein beispielhafter API-Entwurf, kein bestehender Bestell-Endpoint von Webiant. Der Client erzeugt einen Schlüssel für einen Geschäftsvorgang und behält ihn bei einer Wiederholung der Anfrage bei:
POST /orders
Idempotency-Key: objednavka-2026-001
{"external_id":"2026-001","amount_cents":12900,"currency":"EUR"}| Situation | Serververhalten |
|---|---|
| Erster Schlüssel und neuer Inhalt | Bestellung atomar anlegen und die Antwort zum Schlüssel speichern |
| Gleicher Schlüssel und gleicher Inhalt | Gespeichertes Ergebnis ohne neue Bestellung zurückgeben |
| Gleicher Schlüssel, aber anderer Inhalt | Konflikt ablehnen; zum Beispiel HTTP 409 gemäß API-Vertrag |
| Zwei gleichzeitige Anfragen | Eine eindeutige Datenbank-Constraint und eine Transaktion verhindern doppeltes Anlegen |
Die Prüfung „erst suchen, dann erstellen“ reicht bei gleichzeitigen Anfragen nicht aus. Das Schreiben des Schlüssels und der Geschäftsvorgang müssen durch eine Transaktion oder eine gleichwertige atomare Operation geschützt sein. Wird eine E-Mail oder eine Zahlungsanforderung versendet, muss auch dieser Nebeneffekt gesondert behandelt werden.
Test vor der Übergabe der Integration
- Senden Sie dieselbe Anfrage zweimal und vergleichen Sie die Ergebnis-ID.
- Wiederholen Sie die Anfrage nach einem simulierten Timeout.
- Senden Sie zwei identische Anfragen gleichzeitig.
- Ändern Sie den Inhalt bei gleichem Schlüssel und prüfen Sie den vereinbarten Konfliktfall.
- Prüfen Sie, dass eine E-Mail, eine Zahlung oder ein CRM-Eintrag nicht doppelt entsteht.
Vereinbaren Sie bei einer eigenen Integration auch die Aufbewahrungsdauer der Schlüssel und die Regeln für Wiederholungen. Damit hängt zusammen Datenzuordnung zwischen Systemen.
Verstehen Sie, woher die Wiederholung kommt
Ein HTTP-Client weiß oft nicht, ob ein Timeout vor oder nach der Verarbeitung eingetreten ist. Ein erneuter Versuch ist daher eine natürliche Strategie und kein Fehler. Manche Warteschlangen und Webhook-Mechanismen sind auf eine Zustellung mindestens einmal ausgelegt, was Duplikate bewusst in Kauf nimmt. Ein Doppelklick des Nutzers, die Zurück-Navigation im Browser oder ein erneuter Import schaffen weitere Wege zur selben Wirkung.
Erfassen Sie die Operationen, bei denen ein Duplikat ein geschäftliches Problem verursacht. Ein Lesezugriff birgt in der Regel nicht dasselbe Risiko wie das Anlegen einer Zahlung. Eine Aktualisierung auf einen exakten Wert verhält sich anders als ein Befehl zur Erhöhung der Menge. Legen Sie für jede Operation die Identität der Absicht und den Zeitraum fest, in dem eine Wiederholung als dieselbe gilt.
Entwerfen Sie einen stabilen Idempotenzschlüssel
Der Schlüssel soll einmal für eine konkrete geschäftliche Absicht entstehen und bei einer technischen Wiederholung gleich bleiben. Er darf nicht bei jedem Versuch neu generiert werden, da der Server sonst das Duplikat nicht erkennt. Verknüpfen Sie den Gültigkeitsbereich des Schlüssels mit dem Client, dem Konto oder dem Endpunkt, damit eine zufällige Übereinstimmung zwischen verschiedenen Benutzern nicht zu einem Konflikt wird.
Der Server kann einen Fingerabdruck des relevanten Inhalts speichern und denselben Schlüssel mit anderen Parametern ablehnen. So schützt er den Client vor einem Versehen, wenn dieser den Schlüssel für einen anderen Betrag oder ein anderes Produkt erneut verwendet. Beziehen Sie keine Werte in den Vergleich ein, die sich bei jedem Versuch naturgemäß ändern, etwa einen technischen Zeitstempel.
- ein Keyword für eine geschäftliche Absicht
- Bindung an den Client und Art der Operation
- Prüfung geänderter Inhalte
- klare Aufbewahrungsdauer des Status
Speichern Sie Status und Ergebnis atomar
Legen Sie beim ersten Empfang einen Operationsdatensatz so an, dass nicht zwei parallele Worker die Zuständigkeit übernehmen können. Ein eindeutiger Datenbankschlüssel oder ein transaktionaler Mechanismus ist zuverlässiger als ein getrenntes „erst prüfen, dann einfügen“. Der Status kann empfangene, in Verarbeitung befindliche, erfolgreiche und fehlgeschlagene Operationen unterscheiden.
Speichern Sie nach einem Erfolg ein sicheres Ergebnis oder einen Verweis auf das erstellte Objekt. Eine wiederholte Anfrage soll eine konsistente Antwort ohne weitere Wirkung erhalten. Bei langer Verarbeitung kann der Server mitteilen, dass die Operation noch läuft, und einen Status-Endpoint anbieten. Speichern Sie keine unnötigen sensiblen Inhalte nur wegen der Idempotenz.
Behandeln Sie Teilerfolge und die Reihenfolge der Schritte
Eine Operation kann die Bestellung speichern und anschließend beim Versand der E-Mail oder bei einer externen API scheitern. Unterscheiden Sie die zentrale geschäftliche Verpflichtung von nachgelagerten Aufgaben. Verarbeiten Sie Nebenschritte über eine robuste Warteschlange und geben Sie auch ihnen eine eigene Identität. Das gesamte Ergebnis rückgängig zu machen, ist nach einer eingegangenen Zahlung unter Umständen weder möglich noch richtig.
Wenn mehrere Ereignisse dasselbe Objekt verändern, löst Idempotenz allein nicht deren Reihenfolge. Verwenden Sie eine Version, einen erwarteten Zustand oder eine sequenzielle Verarbeitung pro Objekt. Ein älteres Ereignis darf einen neueren finalen Zustand nicht überschreiben. Machen Sie einen Konflikt für eine manuelle Entscheidung sichtbar, wenn er sich nicht sicher per Regel lösen lässt.
Gleichzeitigkeit, Ablauf und Korrektur testen
Senden Sie dieselbe Anfrage parallel, unterbrechen Sie die Verbindung nach dem Absenden und wiederholen Sie sie sowohl während der Verarbeitung als auch nach erfolgreichem Abschluss. Prüfen Sie denselben Schlüssel mit abweichendem Inhalt, einen ungültigen Client und eine Wiederholung nach Ablauf des Aufbewahrungsfensters. Kontrollieren Sie das geschäftliche Ergebnis, den Lagerbestand, den Beleg und die Ereignisse, nicht nur den Statuscode.
Der Betrieb muss Vorgänge sehen können, die in der Verarbeitung hängen geblieben sind, und sicher über deren Fortsetzung entscheiden. Das manuelle Löschen eines Idempotenz-Eintrags kann ein Duplikat auslösen, daher sollten Sie ein kontrolliertes Korrekturverfahren einrichten. Beobachten Sie die Wiederholungsrate; ein plötzlicher Anstieg kann auf einen Timeout, einen Client-Fehler oder ein Netzwerkproblem hinweisen.
- zwei gleichzeitige Versuche mit demselben Schlüssel
- Timeout nach erfolgreichem Speichern des Geschäftsobjekts
- gleicher Schlüssel mit abweichendem Inhalt
- teilweiser Erfolg einer nachgelagerten externen Operation
- kontrollierte Wiederholung nach manueller Korrektur
- Ablauf des gespeicherten Schlüssels während der Wiederherstellung des Dienstes
- sicherer Konflikt bei ungültiger Client-Identität
- ein einziger finaler Beleg in allen Systemen
Häufige Fragen
Ist Idempotenz dasselbe wie Deduplizierung?
Sie hängen zusammen, sind aber nicht identisch. Idempotenz bindet wiederholte technische Versuche an eine Absicht und ein Ergebnis. Deduplizierung kann später separate Datensätze nach Ähnlichkeit oder Geschäftsregeln zusammenführen.
Wer soll den Idempotenzschlüssel erstellen?
In der Regel der Client, der die Grenze einer einzelnen Absicht kennt und den Schlüssel wiederholt verwenden kann. Der Server legt Format, Umfang, Validierung und Aufbewahrungsdauer gemäß dem API-Vertrag fest.
Wie lange sollte das Ergebnis einer Operation aufbewahrt werden?
Nach der längsten realistischen Wiederholung, dem geschäftlichen Risiko und den Speicherkosten. Die Aufbewahrungsregel muss dokumentiert sein; nach ihrem Ablauf kann derselbe Schlüssel ein neues Ergebnis bedeuten.
Quellen und weiterführende Lektüre
Adam Antoni vyvíja weby, aplikácie a softvér na mieru. Prepája firemné systémy, automatizuje procesy a vytvára AI agentov. Pôsobí v Spišskej Novej Vsi a spolupracuje s firmami na celom Slovensku.
