If-Match

Uso

La cabecera If-Match habilita las solicitudes condicionales comparando valores de ETag. El cliente incluye esta cabecera para asegurarse de que el servidor procese la solicitud solo cuando la etiqueta de entidad actual del recurso coincide con uno de los valores indicados.

En los métodos seguros como GET y HEAD, la cabecera If-Match restringe la respuesta a los recursos cuya etiqueta de entidad coincide. Esto selecciona una representación concreta en lugar de validar una caché (para la validación de caché se usa If-None-Match).

En los métodos que cambian el estado, como PUT y DELETE, la cabecera If-Match evita el problema de las actualizaciones perdidas. Cuando dos clientes obtienen el mismo recurso, modifican sus copias de forma independiente e intentan volver a escribirlo, la cabecera If-Match garantiza que solo la primera escritura tenga éxito. La segunda escritura falla con 412 Precondition Failed, porque el ETag cambió tras la primera escritura.

Este patrón se conoce como control de concurrencia optimista. El cliente lee un recurso y su ETag, realiza cambios en local y envía la actualización con If-Match fijado al ETag original. El servidor confirma que el recurso no ha cambiado entretanto antes de aplicar la actualización.

La cabecera If-Match realiza únicamente una comparación fuerte. Las etiquetas de entidad débiles (con el prefijo W/) no coinciden, incluso cuando el valor opaco es idéntico. Este comportamiento estricto garantiza la equivalencia del recurso a nivel de bytes.

Lista de etiquetas de entidad

Uno o varios valores de ETag encerrados entre comillas dobles y separados por comas. El servidor compara cada valor con la etiqueta de entidad actual del recurso.

Comodín (*)

El asterisco * coincide con cualquier representación actual del recurso. Esta forma tiene éxito siempre que el recurso de destino exista, sea cual sea el valor de su etiqueta de entidad. El valor * se usa habitualmente con PUT para evitar crear un recurso nuevo cuando ya existe uno en el URI de destino.

Ejemplo

Un cliente envía una solicitud PUT para actualizar un recurso. La cabecera If-Match lleva el ETag de la respuesta GET original. El servidor aplica la actualización solo cuando el ETag sigue coincidiendo.

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

{"title": "Updated Document"}

Cuando otro cliente ha modificado el recurso, el ETag ya no coincide. El servidor responde con 412 Precondition Failed y rechaza la actualización.

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

Varias etiquetas de entidad se indican como valores separados por comas. La condición se cumple cuando cualquiera de los valores listados coincide con el ETag actual del recurso.

If-Match: "a1b2c3d4", "x9y8z7w6"

La forma con comodín se cumple cuando el recurso existe. Esto evita que un PUT cree accidentalmente un recurso nuevo.

If-Match: *