If-Match

Utilisation

L’en-tête If-Match permet d’effectuer des requêtes conditionnelles en comparant des valeurs d’ETag. Un client inclut cet en-tête pour garantir que le serveur ne traite la requête que si l’entity tag actuel de la ressource correspond à l’une des valeurs listées.

Pour les méthodes sûres comme GET et HEAD, l’en-tête If-Match restreint la réponse aux ressources dont l’entity tag correspond. Cela sélectionne une représentation précise plutôt que de valider un cache (la validation de cache utilise plutôt If-None-Match).

Pour les méthodes qui modifient l’état comme PUT et DELETE, l’en-tête If-Match prévient le problème de la mise à jour perdue. Lorsque deux clients récupèrent la même ressource, modifient leur copie indépendamment et tentent de la réécrire, l’en-tête If-Match garantit que seule la première écriture aboutit. La seconde échoue avec un 412 Precondition Failed car l’ETag a changé après la première écriture.

Ce schéma est connu sous le nom de contrôle de concurrence optimiste. Le client lit une ressource et son ETag, effectue ses modifications localement, puis soumet la mise à jour avec If-Match positionné sur l’ETag d’origine. Le serveur confirme que la ressource n’a pas changé entre-temps avant d’appliquer la mise à jour.

L’en-tête If-Match n’effectue qu’une comparaison forte. Les entity tags faibles (préfixés par W/) ne correspondent pas, même lorsque la valeur opaque est identique. Ce comportement strict garantit l’équivalence de la ressource au niveau de l’octet.

Liste d’entity tags

Une ou plusieurs valeurs d’ETag encadrées par des guillemets doubles et séparées par des virgules. Le serveur confronte chaque valeur à l’entity tag actuel de la ressource.

Caractère générique (*)

L’astérisque * correspond à toute représentation actuelle de la ressource. Cette forme réussit tant que la ressource cible existe, quelle que soit la valeur de son entity tag. La valeur * est couramment utilisée avec PUT pour empêcher la création d’une nouvelle ressource lorsqu’il en existe déjà une à l’URI cible.

Exemple

Un client envoie une requête PUT pour mettre à jour une ressource. L’en-tête If-Match transporte l’ETag issu de la réponse au GET initial. Le serveur n’applique la mise à jour que si l’ETag correspond toujours.

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

{"title": "Updated Document"}

Lorsque la ressource a été modifiée par un autre client, l’ETag ne correspond plus. Le serveur répond 412 Precondition Failed et rejette la mise à jour.

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

Plusieurs entity tags se listent sous forme de valeurs séparées par des virgules. La condition est satisfaite dès que l’une des valeurs listées correspond à l’ETag actuel de la ressource.

If-Match: "a1b2c3d4", "x9y8z7w6"

La forme avec caractère générique réussit lorsque la ressource existe. Cela empêche un PUT de créer accidentellement une nouvelle ressource.

If-Match: *