Ein Aufrufer, der eine POST Anfrage wiederholt, meistens ein Zahlungsanbieter oder Webhook Sender, der sich nicht sicher ist, ob sein Callback angekommen ist, kann die Logik deines Endpunkts am Ende ein zweites Mal ausführen: eine zweite Zeile eingefügt, eine zweite E Mail gesendet, eine zweite Belastung erfasst. Einen Idempotency-Key Header zu senden vermeidet das.
Wie es funktioniert
Sende einen eindeutigen Idempotency-Key Header (ein beliebiger String, den der Aufrufer generiert, eine UUID ist typisch) bei einer POST Anfrage. Wenn bereits eine Anfrage mit genau diesem Schlüssel gegen diesen Endpunkt gelaufen ist, wird die gespeicherte Antwort aus diesem ersten Lauf sofort zurückgesendet, byte für byte, einschließlich ihres Statuscodes, die eigene Logik deines Endpunkts läuft nie ein zweites Mal. Eine Anfrage mit einem noch nicht gesehenen Schlüssel läuft normal, und ihre Antwort wird dann unter diesem Schlüssel für das nächste Mal gespeichert. Das funktioniert automatisch für jeden POST Endpunkt, da ist nichts einzuschalten, ein Aufrufer, der den Header nie sendet, ist davon überhaupt nicht betroffen.
Eine wiederholte Antwort trägt einen Idempotency-Replayed: true Header, sodass du die beiden Fälle auseinanderhalten kannst, falls nötig.
Wie lange ein Schlüssel gemerkt wird
24 Stunden ab der ersten Anfrage, dasselbe Fenster, das die meisten Zahlungsanbieter für ihre eigenen Wiederholungen nutzen. Danach wird derselbe Schlüssel wieder als neu behandelt.
Eine bekannte Einschränkung
Zwei Anfragen, die mit demselben Schlüssel wirklich im selben Moment gesendet werden, können beide die gespeicherte Antwort verpassen und beide die Logik deines Endpunkts ausführen, es gibt keine Sperre zwischen den beiden, nur eine im Nachhinein gespeicherte Antwort. In der Praxis überschneidet sich eine echte Wiederholung (der Aufrufer wartet auf ein Timeout oder einen Fehler, bevor er es erneut versucht) nie so, nur zwei absichtlich parallel gesendete Anfragen würden das tun.
Tipp: Das passt gut zu „Was passiert, wenn ein Endpunkt auf halbem Weg fehlschlägt“, zwischen automatischem Rollback bei Fehlern und einer wiederholten Antwort bei einem erneuten Versuch kann ein Aufrufer einen POST sicher wiederholen, ohne sich in beiden Fällen um doppelte Schreibvorgänge sorgen zu müssen.