Le bon général a gagné la bataille du RESTFUL avant de l’engager: PUT vs PATCH

Le bon général a gagné la bataille du RESTFUL avant de l’engager: PUT vs PATCH

  • Post category:API
  • Reading time:5 mins read

Je viens du développement Objet donc je pratique les opérations CRUD (Create, Read, Update et Delete). 

Lorsque je conçois des contrats d’API, il est obligatoire de spécifier la méthode HTTP à utiliser pour chaque opération. Bon je ne vais pas vous cacher que c’est généralement très simplement:

  • Create – POST
  • Read/Retrieve – GET
  • Update – POST/PUT/PATCH
  • Delete – DELETE
Je suis certain de faire hurler certain avec l’utilisation de POST pour l’update. Rassurez-vous, c’est possible et pratique surtout si vous avez des méthodes saveOrUpdate ou merge. On aura l’occasion d’en reparler dans un prochain article.

Souvenir

Si on fait un petit rappel, toute chose sur Internet est considérée comme une ressource (image, texte, page, police, etc.).

Chacune de ses ressources se trouve à un emplacement (URL).

Petit rappel sur les méthodes de requête HTTP

MéthodeDescription
GETLa méthode GET demande une représentation de la ressource spécifiée. Les requêtes GET doivent uniquement être utilisées afin de récupérer des données.
HEADLa méthode HEAD demande une réponse identique à une requête GET pour laquelle on aura omis le corps de la réponse (on a uniquement l'en-tête).
POSTLa méthode POST est utilisée pour envoyer une entité vers la ressource indiquée. Cela entraîne généralement un changement d'état ou des effets de bord sur le serveur.
PUTLa méthode PUT remplace toutes les représentations actuelles de la ressource visée par le contenu de la requête.
DELETELa méthode DELETE supprime la ressource indiquée.
CONNECTLa méthode CONNECT établit un tunnel vers le serveur identifié par la ressource cible.
OPTIONSLa méthode OPTIONS est utilisée pour décrire les options de communications avec la ressource visée.
TRACELa méthode TRACE réalise un message de test aller/retour en suivant le chemin de la ressource visée.
PATCHLa méthode PATCH est utilisée pour appliquer des modifications partielles à une ressource.

Une bataille équilibrée ?

On va maintenant rentrer dans le vif du sujet de notre match du jour. Si vous pensez que PUT et PATCH font la même chose et sont simplement des alias, désolé vous êtes dans les choux.

Il est vrai que les deux méthodes mettent à jour la ressource à un emplacement, mais elles le font différemment. 

Je vous propose de poser les bases d’une analogie pour bien comprendre l’enjeu de la bataille: la mise à jour de données.

Imaginons qu’Internet soit un lotissement. Vous êtes un promoteur qui pose des maisons préfabriquées. Vous allez localiser les maisons avec une URL.

Supposons que le lotissement soit divisé en parcelles numérotées avec une maison par parcelle de sorte que la maison 1 se trouve sur la parcelle 1 et ainsi de suite. N’oubliez pas que les maisons sont préfabriquées, de sorte qu’elles sont simplement déposées à leur emplacement. 

Voilà le contexte est posé.

A ma gauche, la requête PUT

Lorsque vous effectuez une requête PUT à « https://lotissement.promoteur.com/parcelle-1 » avec une maison préfabriquée, vous dites « S’il vous plaît positionne (PUT) cette maison à l’emplacement marqué comme parcelle 1 ». Cette instruction recherche dans notre lotissement l’emplacement spécifié et remplace le contenu. Si rien ne se trouve à l’endroit, il va tout simplement poser (PUT) la ressource dans la parcelle.  Si une maison est présente, elle sera détruite et remplacer par la nouvelle.
Ainsi, une requête PUT contient toujours une ressource complète. Le résultat est reproductible et identique systématique.

A ma droite, la requête PATCH

Une requête PATCH est utilisée pour apporter des modifications à une partie de la ressource à un emplacement. Autrement dit, il PATCHE la ressource – en modifiant ses propriétés. Il est utilisé pour apporter des mises à jour mineures aux ressources et il n’est pas nécessaire qu’il soit idempotent.Si nous continuons avec notre exemple ci-dessus, nous pourrions facilement modifier la couleur de la façade sur la maison de la parcelle 1 sans avoir à expédier une toute nouvelle maison. Tout ce que nous avons à faire est d’expédier la peinture et de repeindre la maison avec une nouvelle couleur.
Ainsi, une requête PATCH contient toujours une ressource partielle. Le résultat n’est pas reproductible. Si l’emplacement est vide, une erreur est levée.

Résultat du match

minion-boxe

Vous l’aurez compris, les deux requêtes existent pour une bonne raison. Elles ont des forces et des faiblesses opposées ce qui les rendent parfaitement complémentaires.

Lorsque vous composez vos contrats d’API REST, je vous conseille toujours de revenir à la base: le protocole HTTP. Une bonne connaissance de son fonctionnement peut répondre à beaucoup de questions.

Laisser un commentaire

huit + deux =