Méthode de requête PATCH

La méthode HTTP PATCH applique des modifications partielles à une ressource.

PATCH est en quelque sorte analogue au concept de « mise à jour » que l'on trouve dans CRUD (en général, HTTP est différent de CRUD, et il ne faut pas les confondre).

Par rapport à PUT, un PATCH sert d'instructions pour modifier une ressource, tandis que PUT représente un remplacement complet de la ressource. Une requête PUT est toujours idempotente (répéter la même requête plusieurs fois résulte en la ressource restant dans le même état), alors qu'une requête PATCH n'est pas toujours idempotente. Par exemple, si une ressource inclut un compteur auto-incrémenté, une requête PUT écrasera le compteur (puisqu'elle remplace toute la ressource), mais une requête PATCH peut ne pas le faire.

Comme POST, une requête PATCH peut potentiellement avoir des effets secondaires sur d'autres ressources.

Un serveur peut indiquer la prise en charge de PATCH en l'ajoutant à la liste dans l'en-tête Allow ou Access-Control-Allow-Methods (pour CORS). Une autre indication implicite que PATCH est pris en charge est l'en-tête Accept-Patch (généralement après une requête OPTIONS sur une ressource), qui liste les types de médias que le serveur peut comprendre dans une requête PATCH pour une ressource.

Syntaxe

PATCH <request-target>["?"<query>] HTTP/1.1

<request-target>

Identifie la ressource cible de la requête, combinée avec l'information fournie dans l'en-tête Host. Il s'agit d'un chemin absolu (par exemple, /chemin/vers/fichier.html) pour les requêtes vers un serveur d'origine, et d'une URL absolue pour les requêtes vers un proxy (par exemple, http://www.exemple.fr/chemin/vers/fichier.html).

<query> Facultatif

Un composant de requête optionnel précédé d'un point d'interrogation ?. Souvent utilisé pour transmettre des informations d'identification sous forme de paires clé=valeur.

Exemples

Modification réussie d'une ressource

Supposons qu'il existe une ressource sur le serveur représentant un utilisateur avec un identifiant numérique 123 au format suivant :

{
 "firstName": "Exemple",
 "LastName": "Utilisateur",
 "userId": 123,
 "signupDate": "2024-09-09T21:48:58Z",
 "status": "actif",
 "registeredDevice": {
 "id": 1,
 "name": "personnel",
 "manufacturer": {
 "name": "Matériel corp"
 }
 }
}

Au lieu d'envoyer un objet JSON pour écraser entièrement une ressource, un PATCH ne modifie que certaines parties de la ressource. Cette requête met à jour le champ status :

PATCH /users/123 HTTP/1.1
Host: exemple.fr
Content-Type: application/json
Content-Length: 27
Authorization: Bearer ABC123
{
 "status": "suspendu"
}

L'interpretation et l'authentification de la requête PATCH dépendent de l'implémentation. Le succès peut être indiqué par n'importe quel code de réponse réussi. Dans cet exemple, un 204 No Content est utilisé car il n'est pas nécessaire de transmettre un corps avec des informations supplémentaires sur l'opération. Un en-tête ETag est fourni pour que l'appelant puisse effectuer une requête conditionnelle ultérieurement :

HTTP/1.1 204 No Content
Content-Location: /users/123
ETag: "e0023aa4f"

Spécifications

Compatibilité des navigateurs

Le navigateur n'utilise pas la méthode PATCH pour les actions initiées par l'utilisateur·ice, donc la « compatibilité navigateur » ne s'applique pas. Les développeur·euse·s peuvent utiliser cette méthode via fetch().

Voir aussi

• Méthodes de requête HTTP
• Codes de statut de réponse HTTP
• En-têtes HTTP
• 204
• Les en-têtes Allow, Access-Control-Allow-Methods
• Accept-Patch - spécifie les formats de document patch acceptés par le serveur
• Générateur JSON Patch ^(angl.)