If-Match

Verwendung

Der Header If-Match ermöglicht bedingte Anfragen durch den Vergleich von ETag-Werten. Ein Client fügt diesen Header ein, um sicherzustellen, dass der Server die Anfrage nur dann verarbeitet, wenn das aktuelle Entity-Tag der Ressource einem der aufgeführten Werte entspricht.

Bei sicheren Methoden wie GET und HEAD beschränkt der Header If-Match die Antwort auf Ressourcen mit übereinstimmendem Entity-Tag. Damit wird eine bestimmte Repräsentation ausgewählt, statt einen Cache zu validieren (für die Cache-Validierung dient stattdessen If-None-Match).

Bei zustandsändernden Methoden wie PUT und DELETE verhindert der Header If-Match das Problem der verlorenen Aktualisierung. Wenn zwei Clients dieselbe Ressource abrufen, ihre Kopien unabhängig voneinander ändern und zurückschreiben wollen, stellt der Header If-Match sicher, dass nur der erste Schreibvorgang erfolgreich ist. Der zweite Schreibvorgang scheitert mit 412 Precondition Failed, weil sich der ETag nach dem ersten Schreibvorgang geändert hat.

Dieses Muster ist als optimistische Nebenläufigkeitskontrolle bekannt. Der Client liest eine Ressource samt ihrem ETag, nimmt lokal Änderungen vor und sendet die Aktualisierung mit If-Match gesetzt auf den ursprünglichen ETag. Der Server bestätigt, dass sich die Ressource zwischenzeitlich nicht geändert hat, bevor er die Aktualisierung anwendet.

Der Header If-Match führt ausschließlich einen starken Vergleich durch. Schwache Entity-Tags (mit dem Präfix W/) passen nicht, selbst wenn der opake Wert identisch ist. Dieses strikte Verhalten sichert die Gleichheit der Ressource auf Byte-Ebene.

Liste von Entity-Tags

Ein oder mehrere ETag-Werte, in doppelte Anführungszeichen eingeschlossen und durch Kommas getrennt. Der Server prüft jeden Wert gegen das aktuelle Entity-Tag der Ressource.

Wildcard (*)

Das Sternchen * passt auf jede aktuelle Repräsentation der Ressource. Diese Form ist erfolgreich, solange die Zielressource existiert, unabhängig vom Wert ihres Entity-Tags. Ein Wert * wird häufig mit PUT verwendet, um zu verhindern, dass eine neue Ressource angelegt wird, wenn unter der Ziel-URI bereits eine existiert.

Beispiel

Ein Client sendet eine PUT-Anfrage, um eine Ressource zu aktualisieren. Der Header If-Match trägt den ETag aus der ursprünglichen GET-Antwort. Der Server wendet die Aktualisierung nur an, wenn der ETag weiterhin übereinstimmt.

PUT /document/42 HTTP/1.1
Host: api.example.re
Content-Type: application/json
If-Match: "a1b2c3d4"

{"title": "Updated Document"}

Wurde die Ressource von einem anderen Client geändert, stimmt der ETag nicht mehr überein. Der Server antwortet mit 412 Precondition Failed und weist die Aktualisierung zurück.

HTTP/1.1 412 Precondition Failed
Content-Type: application/json
ETag: "e5f6g7h8"

Mehrere Entity-Tags werden als kommagetrennte Werte aufgeführt. Die Bedingung ist erfüllt, sobald einer der aufgeführten Werte dem aktuellen ETag der Ressource entspricht.

If-Match: "a1b2c3d4", "x9y8z7w6"

Die Wildcard-Form ist erfolgreich, wenn die Ressource existiert. Das verhindert, dass ein PUT versehentlich eine neue Ressource anlegt.

If-Match: *