Dans la conception REST API, PUT et PATCH sont deux méthodes HTTP utilisées pour mettre à jour des ressources sur le serveur. La différence entre PUT et PATCH dans les REST API réside dans la façon dont chacune effectue les mises à jour et dans les cas d'usage où elle est la plus adaptée. Ces deux méthodes permettent de modifier des données existantes, mais comprendre la différence entre PUT et PATCH dans une REST API aide les développeurs à faire le meilleur choix selon la nature de la mise à jour à effectuer. Dans cet article, nous explorons cette différence, en abordant le débat PATCH vs mise à jour REST, les cas d'usage de chaque méthode et les critères pour choisir la bonne approche.
Qu'est-ce que PUT dans les REST API ?
Pour comprendre la différence entre PUT et PATCH dans REST APIs, commençons par définir ce qu'est PUT. D'après la Section 9.6 RFC 2616, la méthode PUT dans une requête REST API demande que l'entité incluse soit stockée à l'URI de requête fournie.
Si l'URI de requête désigne une ressource déjà existante, l'entité incluse DOIT être considérée comme une version modifiée de celle qui réside sur le serveur d'origine. Si l'URI de requête ne pointe pas vers une ressource existante et que cet URI peut être défini comme une nouvelle ressource par l'agent utilisateur demandeur, le serveur d'origine peut créer la ressource à cet URI.
Autrement dit, la méthode PUT sert à remplacer intégralement une ressource sur le serveur. Il s'agit donc d'une mise à jour "complète", utilisée lorsqu'un remplacement total de la ressource est nécessaire.
PUT convient particulièrement aux cas d'usage suivants :
- Mettre à jour une ressource complète (par exemple, mettre à jour un profil utilisateur avec toutes les nouvelles informations).
- Remplacer entièrement un élément ou un enregistrement.
- Lorsque l'identité de la ressource est connue et que ses données doivent être entièrement actualisées.
Dans des systèmes comme Elasticsearch, les opérations idempotentes sont indispensables pour garantir la cohérence des données. Par exemple, mettre à jour un document dans Elasticsearch via PUT garantit que la même requête peut être répétée sans effets secondaires indésirables.
Qu'est-ce que PATCH dans les REST API ?
Maintenant que nous avons couvert PUT dans REST APIs, voyons ce qu'est PATCH dans REST APIs et comment il fonctionne, avant de comparer PUT et PATCH dans REST APIs. Tel que défini dans RFC 5789, la méthode PATCH dans une requête REST API demande qu'un ensemble de modifications décrites dans l'entité de requête soient appliquées à la ressource identifiée par l'URI de requête.
C'est là toute la distinction PUT vs PATCH dans REST API : vous n'envoyez que les données à modifier, et le serveur applique ces changements à la ressource existante sans la remplacer entièrement. Les développeurs utilisent souvent des patches pour représenter ces modifications incrémentielles, ce qui limite le volume de données transférées et optimise les mises à jour.
C'est pourquoi la méthode PATCH dans REST API est mieux adaptée aux cas d'usage suivants :
- Mettre à jour uniquement un sous-ensemble de champs d'une ressource (par exemple, modifier l'adresse e-mail ou le numéro de téléphone d'un utilisateur). Un exemple de PATCH API pourrait consister à envoyer uniquement le nouvel e-mail, en laissant les autres champs inchangés.
- Améliorer les performances en réduisant la taille des données envoyées.
- Lorsque vous souhaitez mettre à jour une ressource de façon incrémentielle plutôt que de la remplacer intégralement.
- Utilisez des patches pour encapsuler des modifications ciblées, comme la mise à jour de l'e-mail d'un utilisateur, sans toucher aux données non concernées.
Pour les plateformes comme CMS headless qui gèrent souvent des structures de contenu complexes, utiliser PATCH pour des mises à jour ponctuelles - comme la modification d'un seul champ - permet de réduire la charge serveur et d'améliorer les performances.
Ces deux méthodes étant couvertes, vous devriez avoir une bonne compréhension de ce que sont PUT et PATCH dans les REST API. Avant d'aborder la différence entre PUT et PATCH dans les REST API, il faut parler de l'idempotence dans ces deux méthodes.
L'idempotence dans PUT vs PATCH dans les REST API
Dans les REST API, l'idempotence désigne la propriété d'une opération qui, répétée plusieurs fois avec les mêmes entrées, produit toujours le même résultat. Autrement dit, envoyer la même requête plusieurs fois doit avoir le même effet sur le serveur, quel que soit le nombre d'exécutions. C'est essentiel pour garantir la stabilité et la prévisibilité d'une API. Mais quel est le lien avec la différence entre PUT et PATCH dans les REST API ?
La méthode PUT et l'idempotence
La méthode PUT dans les REST API est toujours idempotente, car elle est conçue pour remplacer intégralement la ressource à un URI donné par les données fournies dans la requête. En d'autres termes, si vous effectuez plusieurs fois une requête PUT avec les mêmes données, le résultat sera toujours identique.
Pourquoi PUT est-il idempotent ? Lorsque vous envoyez une requête PUT, vous indiquez au serveur : "Voici l'état exact et complet que je veux pour cette ressource." Que vous envoyiez la requête une ou plusieurs fois, la ressource obtenue sera toujours la même.
Prenons l'exemple d'une mise à jour de l'adresse e-mail d'un utilisateur. Si vous effectuez plusieurs fois la même requête PUT, le résultat ne changera pas, car la ressource est remplacée par les mêmes données à chaque fois.
Exemple :
| PUT /users/1{"username": "john_doe","email": "[email protected]"} |
Si vous envoyez cette requête plusieurs fois, le résultat sera toujours le même :
| {"username": "john_doe","email": "[email protected]"} |
Même si les données de l'utilisateur sont déjà dans cet état, renvoyer la requête ne change rien. Les données sont remplacées par les mêmes données, donc l'effet de la requête reste identique, quel que soit le nombre de répétitions. C'est ce qui rend PUT idempotent.
La méthode PATCH et l'idempotence
La méthode PATCH dans les REST API est également idempotente en général, mais avec plus de souplesse. Lorsque vous créez des patches, veillez à ce que les opérations soient idempotentes (par exemple, affecter une valeur) afin d'éviter des effets de bord indésirables lors de requêtes répétées. Le caractère idempotent de PATCH dépend de l'opération et des données modifiées.
Pourquoi PATCH est-il idempotent ? Pour les requêtes PATCH, l'idempotence signifie qu'appliquer le même patch plusieurs fois donne toujours le même résultat, à condition que le patch lui-même ne provoque pas d'effets de bord supplémentaires lors d'applications répétées. Si vous appliquez plusieurs fois le même patch avec les mêmes données, le résultat ne devrait pas changer après la première application.
Par exemple, si vous mettez à jour uniquement l'adresse e-mail d'un utilisateur, envoyer plusieurs fois la même requête PATCH ne modifiera pas le résultat après la première fois, même si la requête est répétée plusieurs fois. L'adresse e-mail de l'utilisateur restera la même, et l'état de la ressource ne changera pas.
Exemple de API PATCH :
| PATCH /users/1{"email": "[email protected]"} |
Si l'adresse e-mail était déjà [email protected], appliquer ce PATCH à nouveau ne produira aucun changement, ce qui le rend idempotent.
Cependant, PATCH peut aussi être non idempotent dans certains cas. Par exemple, si une opération PATCH modifie un compteur ou ajoute des éléments à une liste (comme incrémenter un nombre ou ajouter un élément à un tableau), des applications répétées du même PATCH peuvent mener à des résultats différents. Cela violerait la propriété d'idempotence.
Exemple de PATCH API REST non idempotent :
| PATCH /counter/1{"increment": 1} |
Si vous appliquez ce PATCH plusieurs fois, le compteur continuera d'augmenter et produira une valeur différente à chaque fois. Ce n'est pas idempotent, car le résultat change à chaque application.
Maintenant que vous connaissez les bases, examinons quelques scénarios concrets pour mieux comprendre la différence entre PUT et PATCH dans les REST API.
Exemples de scénarios : PUT vs PATCH dans les REST API
La théorie mise à part, voici la différence entre PUT et PATCH à travers des exemples, avec des opérations idempotentes et non idempotentes.
Scénario 1 : Requête PUT - Remplacement d'une ressource complète
Imaginez un endpoint API pour gérer des produits dans un système e-commerce. Vous devez mettre à jour tous les détails d'un produit : son nom, son prix et sa description. C'est un exemple typique de la méthode HTTP PUT vs PATCH, où PUT est utilisé pour remplacer l'intégralité de la ressource produit.
Produit initial :
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
Vous souhaitez mettre à jour le prix et la description du produit. Vous envoyez une requête PUT avec la ressource complète :
Requête PUT :
| PUT /products/1001{"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
Que vous effectuiez cette requête PUT une seule fois ou plusieurs fois, le résultat sera toujours identique. Les informations du produit seront mises à jour avec le nouveau prix et la nouvelle description, et ce à chaque appel. C'est ce qui garantit le caractère idempotent de PUT.
Résultat (après la requête PUT) :
| {"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
Scénario 2 : Requête PATCH - Mise à jour partielle d'une ressource
Voyons maintenant un exemple de requête PATCH pour mettre à jour uniquement une partie des informations du produit, comme sa description. Si vous souhaitez modifier la description sans toucher au prix, PATCH est le bon choix. Pour cela, vous construisez une requête contenant uniquement les champs à modifier, ici la description.
Produit initial :
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
Requête PATCH :
| PATCH /products/1001{"description": "A lightweight, powerful laptop."} |
Lorsque vous envoyez cette requête PATCH, seul le champ description est mis à jour. Si vous envoyez la même requête PATCH plusieurs fois, la description reste inchangée après la première mise à jour : la requête est donc idempotente.
Résultat (après la requête PATCH) :
| {"id": 1001,"name": "Laptop","price": 999.99,"description": "A lightweight, powerful laptop."} |
Si vous appliquez à nouveau le même PATCH, la description du produit sera identique à celle obtenue après le premier PATCH. Le résultat est constant, ce qui rend PATCH idempotent dans ce scénario.
Scénario 3 : Requête PATCH - Opération non idempotente
Examinons un cas où PATCH n'est pas idempotent. Supposons qu'un endpoint gère le solde du portefeuille d'un utilisateur et que vous souhaitiez l'incrémenter. C'est ici qu'apparaît une différence clé entre PUT et PATCH : PATCH ajoute une valeur au solde à chaque appel.
Portefeuille initial :
| GET /users/1/wallet{"id": 1,"balance": 100.00} |
Requête PATCH :
| PATCH /users/1/wallet{"increment": 50.00} |
Cette requête PATCH augmente le solde du portefeuille de 50 $. Si vous l'envoyez plusieurs fois, le solde continue d'augmenter à chaque appel, ce qui produit un résultat différent à chaque fois. C'est ce qui rend cette opération non idempotente : appliquer le même PATCH plusieurs fois change le résultat.
Résultat (après la première requête PATCH) :
| {"id": 1,"balance": 150.00} |
Résultat (après la deuxième requête PATCH) :
| {"id": 1,"balance": 200.00} |
Dans ce cas, PATCH n'est pas idempotent : des requêtes identiques produisent des résultats différents.
Récapitulatif : différences clés entre PUT et PATCH dans REST API
La différence clé entre PUT et PATCH dans REST API réside dans leur façon de gérer les mises à jour. PUT remplace la totalité de la ressource : tout champ absent est effacé, ce qui peut entraîner une perte de données. C'est pourquoi les développeurs utilisent PATCH pour les mises à jour partielles, afin d'éviter d'écraser les champs inchangés et de préserver l'intégrité des données.
PATCH est donc plus efficace pour les mises à jour partielles. Par exemple avec API, si vous souhaitez modifier uniquement l'adresse e-mail d'un utilisateur, PATCH n'envoie que ce champ, contrairement à une requête PUT qui exige l'ensemble des données de l'utilisateur.
Avec PUT, la totalité des données doit être transmise. Chaque champ doit être envoyé, et tout champ absent sera supprimé. PATCH, en revanche, ne transmet que les champs à modifier, ce qui le rend plus efficace, notamment pour les ressources volumineuses avec peu de changements. La méthode PATCH dans REST API permet des requêtes plus ciblées et plus légères, réduisant ainsi le volume de données échangées.
PUT et PATCH sont tous deux idempotents : répéter la même requête produit le même résultat. PUT est toutefois plus prévisible, car il remplace intégralement la ressource. PATCH, lorsqu'il ne modifie que certains champs, peut donner des résultats différents selon la façon dont le serveur gère les mises à jour.
Par exemple, si un PATCH incrémente un compteur, des requêtes répétées peuvent produire des résultats différents. Cela dit, les opérations PATCH API peuvent être conçues pour être idempotentes.
En résumé, la différence entre PUT et PATCH dans REST API tient à la nature des mises à jour : PATCH est destiné aux modifications partielles, PUT au remplacement complet de la ressource. Les deux sont idempotents, mais PATCH peut s'avérer plus complexe à mettre en œuvre.
Conclusion
PUT et PATCH sont deux méthodes HTTP fondamentales dans la conception de REST API, mais elles répondent à des besoins différents — c'est là l'essentiel de la distinction entre PUT et PATCH dans REST API. En comprenant cette différence à travers les exemples présentés dans cet article, vous pouvez améliorer sensiblement l'efficacité, la clarté et les fonctionnalités de votre API. En choisissant la bonne méthode (PATCH ou mise à jour REST) selon votre cas d'usage, vous rendez votre API plus efficace, plus facile à maintenir et plus agréable à utiliser. Tenez toujours compte de la nature de la mise à jour, partielle ou complète, ainsi que de son impact sur les performances et l'intégrité des données, puis choisissez la méthode la mieux adaptée à vos besoins.
