Gleichzeitige Änderungen: ETag und If-Match

Nach dieser Anleitung ändern Sie eine versionierte Ressource so, dass eine gleichzeitige Änderung eines anderen Clients nicht verloren geht: Sie lesen das Kennzeichen aus der Kopfzeile ETag, schicken es als If-Match zurück und lösen einen 409-Konflikt sauber auf.

Wie die Versionsprüfung funktioniert#

Fünf Ressourcen führen ein Feld version: Szenen, Playlisten, Programme (Zeitpläne), Rollen und Displays. Bei einer Änderung senden Sie den gelesenen Wert als Kopfzeile If-Match. Hat inzwischen jemand anderes geschrieben, antwortet die API mit 409 Conflict.OptimisticLock, und Sie lesen neu.

Die Version ist der ETag. Sie steht zweimal in der Antwort: als Feld version im Rumpf und als Kopfzeile ETag: "7" — ein starkes Kennzeichen, kein W/. Beide Auftritte tragen denselben Wert; welchen Sie lesen, ist Ihre Wahl. Die Kopfzeile ist auch für Browser-Clients auf anderen Ursprüngen freigegeben.

ETag senden die Lese- und die Änderungsroute derselben Ressourcen: GET und PATCH auf /v1/scenes/{id}, /v1/playlists/{id}, /v1/schedules/{id}, /v1/roles/{id} und /v1/players/{id} sowie POST /v1/scenes/{id}/versions/{vid}/revert. Trägt eine Antwort ausnahmsweise keine Fassung, bleibt die Kopfzeile weg, statt eine Null zu behaupten.

Schritte#

1. Lesen Sie die Ressource und merken Sie sich die Fassung — aus der Kopfzeile oder aus dem Rumpf:

   curl -sS -D - -o /dev/null "$SZENERA_API/v1/scenes/scn_01KJPX8NH0SZENE00000000001" \
     -H "Authorization: Bearer $SZENERA_API_KEY" | grep -i '^etag:'
   

   ETag: "7"
   

2. Senden Sie die Änderung mit If-Match und genau diesem Wert:

   curl -sS -X PATCH "$SZENERA_API/v1/scenes/scn_01KJPX8NH0SZENE00000000001" \
     -H "Authorization: Bearer $SZENERA_API_KEY" \
     -H "Content-Type: application/json" \
     -H 'If-Match: "7"' \
     -d '{ "description": "Startbild im Schaufenster: Wortmarke, Wochenplan und Uhrzeit." }'
   

   Die Antwort ist die Szene mit der neuen Version (hier auf vier Felder gekürzt):

   { "id": "scn_01KJPX8NH0SZENE00000000001", "name": "Notdienst & Wetter", "version": 8, "updatedAt": "2026-07-06T08:30:00.000Z" }
   

   Ein inhaltsgleicher Patch lässt die Version stehen.

3. Kommt 409 zurück, hat jemand zwischen Schritt 1 und 2 geschrieben:

   {
     "code": "Conflict.OptimisticLock",
     "message": "Scene draft was modified concurrently",
     "traceId": "trc_…",
     "details": { "sceneId": "scn_01KJPX8NH0SZENE00000000001", "expectedVersion": 7 }
   }
   

   Lesen Sie die Ressource neu (Schritt 1), wenden Sie Ihre Änderung auf den frischen Stand an und senden Sie erneut mit der neuen Version. Wiederholen Sie den Patch nicht blind mit der alten Version — das endet wieder in 409.

Optionen#

If-Match nimmt drei Schreibweisen desselben Werts an:

Fünf Operationen erzwingen die Kopfzeile und führen sie in der Referenz als Pflicht-Parameter: PATCH /v1/scenes/{id}, POST /v1/scenes/{id}/versions/{vid}/revert, PATCH /v1/playlists/{id}, PATCH /v1/schedules/{id} und PATCH /v1/roles/{id}. PATCH /v1/players/{id} nimmt sie an, verlangt sie aber nicht: Ohne Kopfzeile prüft die Route gegen Fassung 0 und läuft damit in denselben Konflikt wie eine veraltete Angabe. Bei Programmen liegt version unter schedule.version, bei Rollen unter role.version, bei Displays unter player.version.

Was details bei einem Konflikt trägt, hängt von der Ressource ab: Szenen nennen sceneId und expectedVersion; Rollen resource, resourceId, expectedVersion und actualVersion; Displays playerId, expectedVersion und actualVersion; Playlisten und Programme entity, id und expectedVersion.

Kommandozeile. szenera scene update <id> --version=7 … sendet die Version als If-Match; ohne --version liest der Befehl sie vorher selbst. --retry liest bei einem Konflikt einmal neu und wiederholt. Die Spalte Fassung in szenera scene list ist derselbe Wert. Details unter Befehle für Ihre Organisation.

Ergebnis prüfen#

• Die Antwort auf den Patch ist 200 mit der Ressource, und version ist um eins gestiegen (oder unverändert, wenn der Patch nichts geändert hat).
• Ein zweiter Patch mit dem alten If-Match antwortet 409 Conflict.OptimisticLock.

Wenn etwas nicht klappt#

Weiterführendes#

• Idempotenz von Anfang an
• Das Fehlerformat
• Befehle für Ihre Organisation