PATCH

Utilisation

Une requête PATCH transmet un ensemble d’instructions décrivant comment modifier une ressource existante. Contrairement à PUT, qui remplace la ressource entière, PATCH ne modifie que les champs ou propriétés indiqués.

Le corps de la requête contient un document de correctif dans un format que le serveur sait interpréter. L’en-tête Content-Type identifie le format du correctif. L’en-tête Accept-Patch, présent dans les réponses du serveur, annonce les formats de correctif pris en charge.

Remarque

PATCH n’est pas obsolète. La méthode a été normalisée en 2010 et demeure une composante active de la sémantique HTTP. La confusion vient de ce que PATCH a été ajoutée après les autres méthodes et que certains frameworks anciens n’offrent pas de prise en charge native.

Remarque

PATCH n’offre aucune garantie d’idempotence. Appliquer deux fois le même correctif peut produire des résultats différents (par exemple, ajouter deux fois un élément à une liste). Des correctifs concurrents sur une même ressource risquent d’entrer en conflit en l’absence de requêtes conditionnelles (If-Unmodified-Since ou If-Match).

Formats de correctif courants

JSON Patch exprime les modifications sous la forme d’un tableau ordonné d’opérations : add, remove, replace, move, copy et test.

Content-Type: application/json-patch+json

[
  {"op":"replace","path":"/email",
   "value":"alice@example.re"},
  {"op":"add","path":"/verified","value":true}
]

JSON Merge Patch adopte une approche plus simple. Le document de correctif reproduit la structure de la ressource cible. Les champs présents dans le correctif écrasent les valeurs existantes. Donner à un champ la valeur null supprime ce champ.

Content-Type: application/merge-patch+json

{"email":"alice@example.re","nickname":null}

Atomicité

Le serveur applique l’ensemble des modifications d’un document de correctif comme une seule opération atomique. Si une instruction échoue, le correctif entier est rejeté et la ressource reste inchangée.

Remarque

Une requête PATCH a des effets de bord et n’est pas garantie idempotente. Deux correctifs identiques appliqués successivement à une opération d’« ajout à une liste » produisent un résultat différent d’une application unique.

JSON Merge Patch

Un client met à jour l’adresse e-mail de l’utilisateur 42 au format JSON Merge Patch. Le serveur applique la modification et renvoie 200 OK accompagné de la ressource mise à jour.

Requête

PATCH /users/42 HTTP/1.1
Host: api.example.re
Content-Type: application/merge-patch+json
Content-Length: 28

{"email":"alice@example.re"}

Réponse

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 51

{"id":42,"name":"Alice","email":"alice@example.re"}

JSON Patch

Un client applique deux opérations à une ressource de configuration : le remplacement de l’indicateur debug et l’ajout d’un nouveau champ de niveau de journalisation. Le serveur confirme par un 204 No Content.

Requête

PATCH /config/app HTTP/1.1
Host: api.example.re
Content-Type: application/json-patch+json
Content-Length: 102

[
  {"op":"replace","path":"/debug","value":false},
  {"op":"add","path":"/logLevel","value":"warn"}
]

Réponse

HTTP/1.1 204 No Content

Correctif conditionnel

Une requête conditionnelle utilisant If-Unmodified-Since empêche de modifier une ressource déjà changée par un autre client. Si la ressource a été modifiée après l’horodatage indiqué, le serveur renvoie 412 Precondition Failed.

Requête

PATCH /docs/report.json HTTP/1.1
Host: api.example.re
Content-Type: application/merge-patch+json
If-Unmodified-Since: Mon, 01 Jan 2024 12:00:00 GMT
Content-Length: 21

{"status":"reviewed"}

Réponse

HTTP/1.1 412 Precondition Failed
Content-Length: 0

CORS

Les requêtes PATCH multi-origines déclenchent toujours une vérification préalable CORS. Le navigateur envoie d’abord une requête OPTIONS pour confirmer que le serveur autorise PATCH sur la ressource cible.

PATCH et PUT

PATCH n’envoie que les modifications, ce qui réduit la taille des requêtes et économise de la bande passante pour les ressources volumineuses. PUT envoie la représentation complète à chaque fois, quel que soit le nombre de champs modifiés.

PUT est idempotente. Envoyer deux fois la même requête PUT aboutit au même état du serveur. PATCH n’est pas garantie idempotente, car des opérations telles que l’ajout à une liste produisent un résultat différent à chaque application.

Utilisez PATCH pour mettre à jour des champs précis d’une ressource existante. Utilisez PUT pour remplacer la ressource entière par une nouvelle représentation.

PATCH et POST

PATCH modifie une ressource existante située à un URI connu. POST crée de nouvelles ressources ou déclenche un traitement côté serveur.

PATCH s’appuie sur des sémantiques de correctif définies, telles que JSON Patch et JSON Merge Patch. POST délègue entièrement la sémantique au serveur, sans format prescrit pour le corps de la requête.