Idempotenz bedeutet, dass eine Operation bei mehrfacher Ausführung dasselbe Ergebnis hat wie bei einmaliger. Bei APIs wird das oft über einen Idempotency-Key erreicht.
Das Problem
Netzwerke sind unzuverlässig. Sendet ein System eine Anfrage und erhält keine Antwort, weiß es nicht, ob die Anfrage verarbeitet wurde. Wiederholt es sie, kann eine Zahlung doppelt ausgelöst oder eine Rechnung doppelt erzeugt werden. Genau das soll Idempotenz verhindern.
Wie ein Idempotency-Key funktioniert
- Der Client erzeugt für jede fachliche Operation einen eindeutigen Schlüssel, meist eine zufällige ID, und sendet ihn mit der Anfrage, häufig als HTTP-Header.
- Der Server speichert Schlüssel und Ergebnis der ersten Verarbeitung.
- Kommt dieselbe Anfrage mit demselben Schlüssel erneut an, führt der Server sie nicht noch einmal aus, sondern liefert das gespeicherte Ergebnis zurück.
Der Schlüssel gehört zur Operation, nicht zum einzelnen Versuch. Ein Wiederholungsversuch verwendet also denselben Schlüssel, eine neue Operation einen neuen.
Wo es im Billing wichtig ist
- Auslösen von Zahlungen und Lastschriften, auch beim Wiederholen fehlgeschlagener Zahlungen, siehe Payment Retry Logic
- Anlegen von Rechnungen, Kunden und Abonnements über eine REST-API
- Verarbeiten von Webhooks: Ereignisse können mehrfach zugestellt werden, daher sollte der Empfänger Duplikate erkennen, zum Beispiel über die Ereignis-ID
- Kommunikation mit Zahlungsdienstleistern, die Idempotenz-Schlüssel häufig unterstützen
Praxisregeln
- Schlüssel vor dem ersten Versuch erzeugen und mit der Operation speichern
- Ausreichend zufällige Werte verwenden, zum Beispiel UUIDs
- Schlüssel nur für identische Anfrageinhalte wiederverwenden. Viele Anbieter lehnen abweichende Inhalte zum selben Schlüssel ab.
- Beachten, dass gespeicherte Schlüssel meist nur befristet gelten. Prüfen Sie die Dokumentation des jeweiligen Anbieters.