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

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éthode	Description
GET	La 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.
HEAD	La 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).
POST	La 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.
PUT	La méthode PUT remplace toutes les représentations actuelles de la ressource visée par le contenu de la requête.
DELETE	La méthode DELETE supprime la ressource indiquée.
CONNECT	La méthode CONNECT établit un tunnel vers le serveur identifié par la ressource cible.
OPTIONS	La méthode OPTIONS est utilisée pour décrire les options de communications avec la ressource visée.
TRACE	La méthode TRACE réalise un message de test aller/retour en suivant le chemin de la ressource visée.
PATCH	La 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

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.