PATCH

Syntaxe

Paramètres

Description

Cette méthode permet d'effectuer une modification partielle d'une ressource transmise.

Remarques

• La méthode PATCH demande qu'un ensemble de changements décrits dans l'entité de requête soit appliqué à la ressource identifiée par l'URI de la requête. L'ensemble des modifications est représenté dans un format appelé «patch document» identifié par un type de support. Si l'URI de la requête ne pointe pas vers une ressource existante, le serveur peut créer une nouvelle ressource, selon le type de document de correctif (s'il peut logiquement modifier une ressource nulle) et les autorisations,...
• La différence entre les requêtes PUT et PATCH se reflète dans la façon dont le serveur traite l'entité incluse pour modifier la ressource identifiée par l'URI de la requête. Dans une requête PUT, l'entité incluse est considérée comme une version modifiée de la ressource entreposée sur le serveur d'origine et le client demande que la version entreposée soit remplacée. Avec PATCH, cependant, l'entité jointe contient un ensemble d'instructions décrivant comment une ressource résidant actuellement sur le serveur d'origine doit être modifiée pour produire une nouvelle version. La méthode PATCH affecte la ressource identifiée par l'URI de la requête, et elle peut également avoir des effets secondaires sur d'autres ressources; c'est-à-dire que de nouvelles ressources peuvent être créées, ou celles existantes modifiées, par l'application d'un PATCH.
• Une requête PATCH peut être émise de manière à être idempotente, cette situation permettant également d'éviter les mauvais résultats des collisions entre deux requêtes PATCH sur la même ressource dans un délai similaire. Les collisions provenant de plusieurs requêtes PATCH peuvent être plus dangereuses que les collisions PUT car certains formats de patch doivent fonctionner à partir d'un point de base connu, sinon ils corrompent la ressource. Les clients utilisant ce type d'application de correctif devraient utiliser une requête conditionnelle telle que la requête échouera si la ressource a été mise à jour depuis le dernier accès du client à la ressource. Par exemple, le client peut utiliser un ETag: de poids fort dans un entête If-Match: sur la requête PATCH.
• Il existe également des cas où les formats de correctifs n'ont pas besoin de fonctionner à partir d'un point de base connu (par exemple, l'ajout de lignes de texte aux fichiers de journals de bord ou la non collision de lignes aux tables de base de données), auquel cas le même soin dans les requêtes des clients n'est pas nécessaire.
• Le serveur doit appliquer l'ensemble des modifications de manière atomique et ne jamais fournir (par exemple, en réponse à un GET pendant cette opération) une représentation partiellement modifiée. Si le document de correctif complet ne peut pas être appliqué avec succès, le serveur ne doit pas appliquer les modifications. La détermination de ce qui constitue un PATCH réussi peut varier en fonction du document de patch et du type de ressource(s) en cours de modification. Par exemple, l'utilitaire commun «diff» peut générer un document de correctif s'appliquant à plusieurs fichiers dans une hiérarchie de répertoires. L'exigence d'atomicité s'applique à tous les fichiers directement affectés.
• Si la requête passe par un cache et que l'URI de requête identifie une ou plusieurs entités actuellement mises en cache, ces entrées devraient être traitées comme périmées. Une réponse à cette méthode ne peut être mise en cache que si elle contient des informations de fraîcheur explicites (comme un entête Expires: ou une directive «Cache-Control: max-age») ainsi que l'entête Content-Location: correspondant à l'URI de la requête, indiquant que le PATCH le corps de réponse est une représentation des ressources. Une réponse PATCH mise en cache ne peut être utilisée que pour répondre aux requêtes GET et HEAD suivantes; il ne doit pas être utilisé pour répondre à d'autres méthodes (en particulier, PATCH).
• Notez que les entêtes d'entité contenus dans la requête s'appliquent uniquement au document de correction contenu et ne doivent pas être appliqués à la ressource en cours de modification. Ainsi, un entête Content-Language: pourrait être présent sur la requête, mais cela signifierait seulement (pour tout ce qui en vaut la peine) que le document de patch avait une langue. Les serveurs ne devraient pas entreposer de tels entêtes, sauf en tant qu'informations de trace, et ne devraient pas utiliser ces valeurs d'entête de la même manière qu'elles pourraient être utilisées dans les requêtes PUT. Par conséquent, ce document ne spécifie pas un moyen de modifier la valeur Content-Type: ou Content-Language: d'un document via des entêtes, bien qu'un mécanisme pourrait bien être conçu pour atteindre cet objectif via un correctif.
• Il n'y a aucune garantie qu'une ressource peut être modifiée avec PATCH. En outre, il est prévu que différents formats de document de correction seront appropriés pour différents types de ressources et qu'aucun format unique ne conviendra à tous les types de ressources. Par conséquent, il n'y a pas de valeur par défaut unique.