Idempotenz von Anfang an

Nach dieser Anleitung erzeugt eine Wiederholung nach Netzabbruch keinen zweiten Vorgang mehr: Ihr Client schickt zu jedem verändernden Aufruf einen Idempotency-Key, und die Plattform liefert bei einer Wiederholung die gespeicherte Antwort statt einer neuen Ressource.

Schritte#

1. Erzeugen Sie je Vorgang einen Schlüssel von mindestens 8 Zeichen — am besten einen, den Ihr System ohnehin kennt, etwa eine Auftrags- oder Importnummer. Er muss nur innerhalb Ihrer Organisation für diese Methode und diesen Pfad eindeutig sein.

   export IDEM="import-2026-09-08-0042"
   

2. Senden Sie den Schlüssel als Kopfzeile Idempotency-Key mit dem verändernden Aufruf:

   curl -sSi "$SZENERA_API/v1/folders" \
     -H "Authorization: Bearer $SZENERA_API_KEY" \
     -H "Idempotency-Key: $IDEM" \
     -H "Content-Type: application/json" \
     -d '{"name":"Videos"}'
   

   {
     "id": "fld_01KKEQQF80MAPPE00000000003",
     "name": "Videos",
     "kind": "regular",
     "path": "/Videos",
     "parentFolderId": null,
     "depth": 0,
     "createdAt": "2026-03-11T15:20:00.000Z"
   }
   

   Die Plattform speichert Status, Rumpf und die Kopfzeilen ETag, Location und X-Trace-Id dieser ersten Antwort für 24 Stunden.

3. Bricht die Verbindung ab, bevor die Antwort bei Ihnen ankommt, wiederholen Sie denselben Aufruf mit demselben Schlüssel und demselben Rumpf. Es entsteht kein zweiter Ordner.

4. Erkennen Sie die Wiederholung an der Kopfzeile Idempotent-Replay: true: Sie bekamen die gespeicherte Antwort, die Aktion lief nicht erneut.

   HTTP/1.1 201 Created
   Idempotent-Replay: true
   

Regeln, die dabei gelten#

• Der Zwischenspeicher ist getrennt je Organisation, Methode und Pfad. Derselbe Schlüssel auf einem anderen Pfad oder mit einer anderen Methode trifft einen anderen Eintrag.
• Kürzer als 8 Zeichen: 422 Validation.Failed.
• Derselbe Schlüssel mit einem anderen Rumpf ist keine Wiederholung, sondern ein zweiter Vorgang unter geborgtem Namen: 422 Validation.IdempotencyKeyReused. Weder die alte Antwort noch ein neuer Vorgang kommt zurück.
• Auf Routen, die den Schlüssel erzwingen, fehlt er: 409 Validation.IdempotencyKeyRequired.
• Nach 24 Stunden ist der Eintrag verfallen; derselbe Schlüssel führt den Vorgang dann erneut aus.
• Für Änderungen an versionierten Ressourcen (Szenen, Playlisten, Programme, Rollen, Displays) kommt If-Match mit der gelesenen version aus dem Rumpf hinzu — der Idempotency-Key schützt vor der doppelten Ausführung, If-Match vor dem Überschreiben fremder Änderungen. Siehe ETag und If-Match.

Über die Kommandozeile#

szenera api post und die übrigen schreibenden Befehle erzeugen ohne Angabe je Aufruf einen frischen Schlüssel. Nur zum Fortsetzen einer abgebrochenen Wiederholung setzen Sie ihn selbst:

szenera api post /v1/folders '{"name":"Videos"}' --idempotency-key="$IDEM"

Ergebnis prüfen#

• Der zweite Aufruf liefert denselben Status und denselben Rumpf wie der erste — dieselbe Kennung fld_… — und zusätzlich Idempotent-Replay: true.
• Die Ordnerliste enthält den Ordner genau einmal.

Wenn etwas nicht klappt#

Weiterführendes#

• ETag und If-Match
• Fehlerformat
• Skripte und CI