Patcher le verbe - Patch verb
En informatique, la méthode PATCH est une méthode de requête prise en charge par le protocole HTTP ( Hypertext Transfer Protocol ) pour apporter des modifications partielles à une ressource existante. La méthode PATCH fournit une entité contenant une liste de modifications à appliquer à la ressource demandée à l'aide de l' URI ( Uniform Resource Identifier ) HTTP . La liste des modifications est fournie sous la forme d'un document PATCH. Si la ressource demandée n'existe pas, le serveur peut créer la ressource en fonction du type de support du document PATCH et des autorisations. Les modifications décrites dans le document PATCH doivent être sémantiquement bien définies mais peuvent avoir un type de support différent de celui de la ressource patchée. Des cadres tels que XML , JSON peuvent être utilisés pour décrire les modifications dans le document PATCH.
Histoire de PATCH
Conformément à la sémantique définie dans le protocole HTTP , les méthodes GET , PUT et POST doivent utiliser une représentation complète de la ressource. La méthode PUT qui peut être utilisée pour la création ou le remplacement de ressources est idempotente et ne peut être utilisée que pour des mises à jour complètes. Les formulaires d'édition utilisés dans l' application Ruby on Rails conventionnelle doivent créer de nouvelles ressources en appliquant des mises à jour partielles à une ressource parent. En raison de cette exigence, la méthode PATCH a été ajoutée au protocole HTTP en 2010.
METTRE vs PATCH vs POST
HTTP est le fondement de la communication de données pour le World Wide Web . Il s'agit d'un protocole de demande-réponse qui aide les utilisateurs à communiquer avec le serveur pour effectuer des opérations CRUD . HTTP prend en charge un certain nombre de méthodes de requête telles que PUT , POST et PATCH pour créer ou mettre à jour des ressources.
La principale différence entre la méthode PUT et PATCH est que la méthode PUT utilise l' URI de requête pour fournir une version modifiée de la ressource demandée qui remplace la version originale de la ressource, tandis que la méthode PATCH fournit un ensemble d'instructions pour modifier la ressource. Si le document PATCH est plus grand que la taille de la nouvelle version de la ressource envoyée par la méthode PUT alors la méthode PUT est préférée.
La méthode POST peut être utilisée pour envoyer des mises à jour partielles à une ressource. La principale différence entre les méthodes POST et PATCH est que la méthode POST ne peut être utilisée que lorsqu'elle est écrite pour prendre en charge les applications ou que les applications prennent en charge sa sémantique, tandis que la méthode PATCH peut être utilisée de manière générique et ne nécessite pas de support d'application. Si le résultat de l'utilisation de la méthode PATCH n'est pas connu, la méthode POST est préférée.
Ressources de correctifs
La méthode PATCH est atomique . Soit toutes les modifications spécifiées par la méthode PATCH sont appliquées, soit aucune des modifications n'est appliquée par le serveur. Il existe de nombreuses façons de vérifier si un correctif a été appliqué avec succès. Par exemple, l' utilitaire 'diff' peut être appliqué à l'ancienne version et à la nouvelle version d'un fichier pour trouver les différences entre elles.
Une réponse PATCH mise en cache est considérée comme périmée. Il ne peut être utilisé que pour les requêtes GET et HEAD qui peuvent suivre la requête PATCH.
Les en-têtes d'entité dans le document PATCH ne s'appliquent qu'au document PATCH et ne peuvent pas être appliqués à la ressource demandée.
Il n'y a pas de format standard pour le document PATCH et il est différent pour différents types de ressources. Le serveur doit vérifier si le document PATCH reçu est approprié pour la ressource demandée.
Un document JSON Patch ressemblerait à
{ "op": "add", "path": "/count", "value": 1 }
"op" représente l'opération effectuée sur la ressource. "path" représente la ressource en cours de modification. « valeur » représente le montant ajouté à la ressource existante. Avant d'appliquer les modifications dans le document PATCH, le serveur doit vérifier si le document PATCH reçu est approprié pour la ressource demandée. Si la demande PATCH réussit, elle renvoie une réponse 204 .
Un document XML PATCH ressemblerait à
<add sel="doc/user[@email='xyz@abc.com']" type="@address">
ABC Road
</add>
L'élément <user> est localisé à l'aide de l'attribut 'email'. Un nouvel attribut 'address' avec la valeur "ABC Road" est ajouté à l'élément <user>.
Exemple
Un exemple simple de demande de PATCH
PATCH /example.txt HTTP/1.1 Host: www.example.com Content-Type: application/example If-Match: "c0b42b66e" Content-Length: 120
[changes]
[changements] est le document de correctif contenant toutes les modifications qui doivent être apportées à la ressource example.txt
Réponse PATCH réussie au fichier texte existant :
HTTP/1.1 204 No Content Content-Location: /example.txt ETag: "c0b42b66f"
La réponse 204 signifie que la demande a été traitée avec succès.
Compromis entre PUT et PATCH
L'utilisation de la méthode PUT consomme plus de bande passante que la méthode PATCH lorsque seules quelques modifications doivent être appliquées à une ressource. Mais lorsque la méthode PATCH est utilisée, cela implique généralement de récupérer la ressource sur le serveur, de comparer les fichiers d'origine et les nouveaux, de créer et d'envoyer un fichier diff. Côté serveur, le serveur doit lire le fichier diff et effectuer les modifications. Cela implique beaucoup de frais généraux par rapport à la méthode PUT. En revanche, la méthode PUT nécessite qu'un GET soit effectué avant le PUT et il est difficile de s'assurer que la ressource n'est pas modifiée entre les requêtes GET et PUT .
Mise en garde
La méthode PATCH n'est pas « sûre » au sens de la RFC 2616 : elle peut modifier des ressources, pas forcément limitées à celles mentionnées dans l' URI .
La méthode PATCH n'est pas idempotente . Il peut être rendu idempotent en utilisant une requête conditionnelle. Lorsqu'un client fait une demande conditionnelle à une ressource, la demande réussit uniquement si la ressource n'a pas été mise à jour depuis la dernière fois que le client a accédé à cette ressource. Cela permet également d'éviter la corruption de la ressource, car certaines mises à jour d'une ressource ne peuvent être effectuées qu'à partir d'un certain point de base.
La gestion des erreurs
Une requête PATCH peut échouer si l'une des erreurs suivantes se produit :
Document de correctif mal formé
Le serveur renvoie une réponse 400 (Mauvaise demande) si le document PATCH n'est pas formaté comme requis.
Document de correctif non pris en charge
Le serveur renvoie une réponse 415 (Unsupported Media Type ) avec un en -tête de réponse Accept-Patch contenant les types de supports pris en charge lorsque le client envoie un document de correctif non pris en charge. Cela informe le client que le document PATCH envoyé par le client ne peut pas être appliqué à la ressource demandée.
Demande impossible à traiter
Le serveur renvoie une réponse 422 (Unprocessable Entity) lorsque le serveur comprend le document PATCH mais est incapable de modifier la ressource demandée soit parce que cela rend la ressource invalide soit parce que cela entraîne un autre état d'erreur.
Ressource introuvable
Le serveur renvoie une réponse 404 (Not Found) lorsque le document PATCH ne peut pas être appliqué à une ressource inexistante.
État conflictuel
Le serveur renvoie une réponse 409 (Conflit) lorsqu'il ne peut pas appliquer de correctif pour l'état actuel de la ressource.
Modification conflictuelle
Le serveur renvoie une réponse 412 (Precondition Failed) lorsque la précondition fournie par le client à l'aide de l'en -tête If-Match ou If-Unmodified-Since échoue. Si aucune condition préalable n'est fournie et qu'il y a une modification conflictuelle, le serveur renvoie une réponse 409 (Conflit).
Modification simultanée
Le serveur renvoie une réponse 409 (Conflit) si les requêtes PATCH à une certaine ressource doivent être appliquées dans un certain ordre et que le serveur n'est pas en mesure de gérer les requêtes PATCH simultanées.
Considérations de sécurité
La requête PATCH doit utiliser des mécanismes tels que des requêtes conditionnelles utilisant des Etags et l'en - tête de requête If-Match pour s'assurer que les données ne sont pas corrompues lors de la correction. En cas d'échec d'une requête PATCH ou d'échec du canal ou d'un timeout, le client peut utiliser une requête GET pour vérifier l'état de la ressource. Le serveur doit s'assurer que les clients malveillants n'utilisent pas la méthode PATCH pour consommer des ressources serveur excessives.