2. La méthode PATCH (The PATCH Method)
2. La méthode PATCH (The PATCH Method)
La méthode PATCH demande qu'un ensemble de modifications décrites dans l'entité de requête (request entity) soit appliqué à la ressource identifiée par le Request-URI. Cet ensemble de modifications est représenté dans un format appelé "document de correctif (patch document)" identifié par un type de média (media type). Si le Request-URI ne pointe pas vers une ressource existante, le serveur PEUT créer une nouvelle ressource, en fonction du type de document de correctif (s'il peut logiquement modifier une ressource nulle) et des permissions, etc.
La différence entre les requêtes PUT et PATCH se reflète dans la façon dont le serveur traite l'entité contenue pour modifier la ressource identifiée par le Request-URI. Dans une requête PUT, l'entité contenue est considérée comme une version modifiée de la ressource stockée sur le serveur d'origine (origin server), et le client demande que la version stockée soit remplacée. Avec PATCH, cependant, l'entité contenue contient un ensemble d'instructions (instructions) décrivant comment une ressource résidant actuellement sur le serveur d'origine devrait être modifiée pour produire une nouvelle version. La méthode PATCH affecte la ressource identifiée par le Request-URI, et elle PEUT également avoir des effets secondaires (side effects) sur d'autres ressources; c'est-à-dire que de nouvelles ressources peuvent être créées, ou des ressources existantes modifiées, par l'application d'un PATCH.
PATCH n'est ni sûr (safe) ni idempotent (idempotent) comme défini par [RFC2616], section 9.1.
Une requête PATCH peut être émise de manière à être idempotente, ce qui aide également à prévenir les mauvais résultats des collisions (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 correctif doivent fonctionner à partir d'un point de base connu (base-point), sinon ils corrompront la ressource. Les clients utilisant ce type d'application de correctif DEVRAIENT (SHOULD) utiliser une requête conditionnelle (conditional request) de sorte que la requête échouera si la ressource a été mise à jour depuis le dernier accès du client. Par exemple, le client peut utiliser un ETag fort [RFC2616] dans un en-tête If-Match sur la requête PATCH.
Il existe également des cas où les formats de correctif n'ont pas besoin de fonctionner à partir d'un point de base connu (par exemple, ajouter des lignes de texte à des fichiers journaux, ou des lignes non conflictuelles à des 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 (MUST) appliquer l'ensemble complet des modifications de manière atomique (atomically) et ne jamais fournir (par exemple, en réponse à un GET pendant cette opération) une représentation partiellement modifiée (representation). Si l'ensemble du document de correctif ne peut pas être appliqué avec succès, alors le serveur NE DOIT PAS (MUST NOT) appliquer aucune des modifications. La détermination de ce qui constitue un PATCH réussi peut varier en fonction du document de correctif et du type de ressource(s) modifiée(s). Par exemple, l'utilitaire 'diff' commun peut générer un document de correctif qui s'applique à plusieurs fichiers dans une hiérarchie de répertoires. L'exigence d'atomicité s'applique à tous les fichiers affectés par le correctif, pas seulement à l'un d'entre eux. Voir "Gestion des erreurs (Error Handling)", section 2.2, pour plus de détails sur les codes d'état et les conditions d'erreur possibles.
Si la requête passe par un cache et que le Request-URI identifie une ou plusieurs entités actuellement mises en cache, ces entrées DEVRAIENT (SHOULD) être traitées comme obsolètes (stale). Une réponse à cette méthode n'est cacheable (cacheable) que si elle contient des informations de fraîcheur explicites (freshness information) (telles qu'un en-tête Expires ou une directive "Cache-Control: max-age") ainsi que l'en-tête Content-Location correspondant au Request-URI, indiquant que le corps de la réponse PATCH est une représentation de ressource. Une réponse PATCH mise en cache ne peut être utilisée que pour répondre aux requêtes GET et HEAD ultérieures; elle NE DOIT PAS (MUST NOT) être utilisée pour répondre à d'autres méthodes (telles que PATCH).
Notez que les en-têtes d'entité (entity-headers) contenus dans la requête s'appliquent uniquement au document de correctif contenu et NE DOIVENT PAS (MUST NOT) être appliqués à la ressource modifiée. Ainsi, un en-tête Content-Language pourrait être présent sur la requête, mais cela ne signifierait que (pour ce que cela vaut) que le document de correctif a une langue. Les serveurs NE DEVRAIENT PAS (SHOULD NOT) stocker de tels en-têtes sauf comme informations de traçage (trace information), et NE DEVRAIENT PAS (SHOULD NOT) utiliser de telles valeurs d'en-tête de la même manière qu'elles pourraient être utilisées sur les requêtes PUT. Par conséquent, ce document ne spécifie pas de moyen de modifier la valeur Content-Type ou Content-Language d'un document via des en-têtes, bien qu'un mécanisme puisse être conçu pour atteindre cet objectif via un document de correctif.
Il n'y a aucune garantie qu'une ressource puisse être modifiée avec PATCH. De plus, on s'attend à ce que différents formats de documents de correctif soient appropriés pour différents types de ressources et qu'aucun format unique ne soit approprié pour tous les types de ressources. Par conséquent, il n'existe pas de format de document de correctif par défaut unique que les implémentations doivent prendre en charge. Les serveurs DOIVENT (MUST) s'assurer qu'un document de correctif reçu est approprié pour le type de ressource identifiée par le Request-URI cible.
Les clients doivent choisir quand utiliser PATCH plutôt que PUT. Par exemple, si la taille du document de correctif est supérieure à la taille des nouvelles données de ressource qui seraient utilisées dans un PUT, alors il pourrait être judicieux d'utiliser PUT au lieu de PATCH. Une comparaison avec POST est encore plus difficile, car POST est utilisé de manières très variées et peut englober des opérations de type PUT et PATCH si le serveur le choisit. Si l'opération ne modifie pas la ressource identifiée par le Request-URI de manière prévisible, POST devrait être envisagé au lieu de PATCH ou PUT.