Dans la conception de l'API RESTful, PUT et PATCH sont deux méthodes HTTP utilisées pour mettre à jour les ressources sur le serveur, mais la différence entre PUT et PATCH dans les API REST réside dans la manière dont elles effectuent les mises à jour et les scénarios dans lesquels chacune est la plus appropriée. Les deux méthodes sont conçues pour modifier les données existantes, mais comprendre la différence PUT et PATCH dans l'API REST peut aider les développeurs à faire le meilleur choix en fonction de la nature de la mise à jour qu'ils doivent effectuer. Dans cet article de blog, nous explorerons la différence PUT et PATCH dans l'API REST, en nous concentrant sur le débat PATCH vs update REST, quand utiliser chacun, et fournirons des conseils sur le choix de la bonne méthode pour différents cas d'utilisation.
Qu’est-ce que PUT dans les API REST ?
Pour comprendre la différence entre PUT et PATCH dans les API REST, nous devons d'abord savoir ce qu'est PUT en premier lieu. Basé sur Section 9.6 RFC 2616, la méthode PUT de l'API REST demande que l'entité incluse soit stockée sous le Request-URI fourni.
Si le Request-URI fait référence à une ressource déjà existante, l'entité incluse DEVRAIT être considérée comme une version modifiée de celle résidant sur le serveur d'origine. Si le Request-URI 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 avec cet URI.
En d’autres termes, la méthode PUT permet de mettre à jour l’intégralité d’une ressource sur le serveur. Cela fait de PUT une mise à jour plus « complète », souvent utilisée lorsqu'un remplacement complet de la ressource est nécessaire.
Ainsi, PUT est le meilleur pour les cas d’utilisation suivants :
- Mettre à jour une ressource complète (par exemple, mettre à jour un profil utilisateur avec toutes les nouvelles informations).
- Remplacement d'un élément ou d'un enregistrement entier.
- Lorsque l’identité de la ressource est claire et que ses données doivent être entièrement actualisées.
Dans des systèmes comme Recherche élastique, des opérations idempotentes sont nécessaires pour garantir la cohérence des données. Par exemple, la mise à jour d'un document dans Elasticsearch à l'aide de PUT garantit que la même requête peut être répétée sans effets secondaires involontaires.
Qu’est-ce que PATCH dans les API REST ?
Maintenant que nous avons couvert PUT dans les API REST, examinons ce qu'est PATCH dans les API REST et comment il fonctionne avant de comparer PUT et PATCH dans les API REST. Tel que défini dans RFC5789, la méthode PATCH de l'API REST demande qu'un ensemble de modifications décrites dans l'entité de requête soit appliqué à la ressource identifiée par le Request-URI.
Cela correspond à la distinction entre l'API PUT et PATCH REST, où vous envoyez uniquement les données qui doivent être modifiées et le serveur applique ces modifications à la ressource existante sans modifier l'intégralité de la ressource. Les développeurs créent souvent des correctifs pour représenter ces modifications incrémentielles, garantissant ainsi un transfert de données minimal et des mises à jour efficaces.
C'est pourquoi la méthode PATCH dans l'API REST est mieux adaptée aux cas d'utilisation suivants :
- Mettre à jour uniquement un sous-ensemble de champs dans une ressource (par exemple, modifier l'adresse e-mail ou le numéro de téléphone d'un utilisateur). Un exemple d'API PATCH pourrait impliquer d'envoyer uniquement le nouvel e-mail, en laissant les autres champs intacts.
- Améliorer les performances en minimisant la charge utile des données.
- Lorsque vous souhaitez mettre à jour une ressource de manière incrémentielle plutôt que de la remplacer complètement.
- Créez des correctifs pour encapsuler des modifications de champs spécifiques, comme la modification de l'e-mail d'un utilisateur, sans affecter les données non liées.
Pour les plateformes comme CMS sans tête qui gèrent souvent des structures de contenu complexes, l'utilisation de PATCH pour des mises à jour plus petites (comme la modification d'un seul champ) peut réduire la charge du serveur et améliorer les performances.
Avec ces deux méthodes couvertes, vous devriez avoir une bonne idée de ce que sont PUT et PATCH dans les API REST. Cependant, avant d'aborder la différence entre PUT et PATCH dans les API REST, nous devons parler d'idempotence dans ces deux méthodes.
Idempotence dans PUT Vs Patch dans les API REST
Dans les API REST, l'idempotence fait référence à la propriété d'une opération qui, répétée plusieurs fois avec les mêmes entrées, aboutit au même résultat. Cela signifie que faire la même requête plusieurs fois devrait avoir le même effet sur le serveur, quel que soit le nombre de fois où elle est exécutée. Ceci est important pour garantir la stabilité et la prévisibilité d’une API. Mais en quoi est-ce pertinent par rapport à la différence PUT et PATCH dans l'API REST ?
Méthode PUT et idempotence
La méthode PUT dans l'API REST est toujours idempotente car elle est conçue pour remplacer l'intégralité de la ressource à un URI spécifié 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 de ressources, le résultat sera toujours le même.
Pourquoi PUT est-il idempotent ? Lorsque vous effectuez une requête PUT, vous dites essentiellement au serveur : « C'est l'état complet et exact que je souhaite pour cette ressource. » Que vous émettez la requête PUT une ou plusieurs fois, la ressource résultante sera toujours identique.
Par exemple, considérons le scénario dans lequel vous mettez à jour l’adresse e-mail d’un utilisateur. Si vous effectuez plusieurs fois la même requête PUT, le résultat ne sera pas modifié car la ressource est remplacée à chaque fois par les mêmes données.
Exemple:
| PUT /users/1{« nom d'utilisateur » : « john_doe », « email » : « [email protected] »} |
Si vous envoyez cette requête plusieurs fois, le résultat sera toujours le même :
| {"nom d'utilisateur": "john_doe", "email": "[email protected]"} |
Même si les données de l’utilisateur sont déjà celles-ci, renvoyer la demande ne change rien. Il remplace les données par les mêmes données, de sorte que l'effet de la requête reste le même quel que soit le nombre de fois où elle est répétée. C’est ce qui rend PUT idempotent.
Méthode PATCH et idempotence
La méthode PATCH de l'API REST, en revanche, est également généralement idempotente, mais avec plus de flexibilité. Lorsque vous créez des correctifs, assurez-vous que les opérations sont idempotentes (par exemple, définir une valeur) pour éviter les effets secondaires involontaires des demandes répétées. Le fait que PATCH soit idempotent 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 plusieurs fois le même correctif aura le même résultat. Cela est vrai tant que le patch lui-même ne provoque pas d’effets secondaires ou de modifications supplémentaires lorsqu’il est appliqué à plusieurs reprises. Si vous continuez à appliquer le même patch avec les mêmes données, le résultat devrait rester inchangé après la première application.
Par exemple, si vous mettez uniquement à jour l’e-mail d’un utilisateur, l’envoi répété de la même requête PATCH ne changera pas le résultat après la première fois, même si la requête est effectuée plusieurs fois. L'e-mail de l'utilisateur restera le même et l'état de la ressource ne changera pas.
Exemple d'API PATCH :
| PATCH /users/1{« email » : « [email protected] »} |
Si l'e-mail était déjà [email protected], l'application à nouveau de ce PATCH n'entraînera aucun changement, le rendant idempotent.
Cependant, PATCH peut également être non idempotent dans certains cas. Par exemple, si une opération PATCH modifie un compteur ou ajoute des éléments à une liste (comme l'incrémentation d'un nombre ou l'ajout à un tableau), des applications répétées du même PATCH peuvent conduire à des résultats différents. Cela violerait la propriété d'idempotence.
Exemple de PATCH REST API non idempotent :
| PATCH /counter/1{« incrément » : 1} |
Si vous appliquez ce PATCH à plusieurs reprises, le compteur continuera d'augmenter, ce qui entraînera des valeurs différentes à chaque fois. Ce n’est pas idempotent car le résultat change à chaque candidature.
Maintenant que vous connaissez l'essentiel, nous pouvons examiner quelques exemples de scénarios pour mieux comprendre la différence entre PUT et PATCH dans les API REST.
Exemples de scénarios : PUT vs PATCH dans les API REST
Théorie mise à part, examinons la différence entre PUT et PATCH avec des exemples, incluant des opérations idempotentes et non idempotentes.
Scénario 1 : demande PUT – Remplacement d'une ressource entière
Imaginez un point de terminaison API pour gérer les produits dans un système de commerce électronique. Vous devez mettre à jour tous les détails d'un produit, y compris son nom, son prix et sa description. Il s'agit d'un exemple typique de la méthode HTTP PUT vs PATCH, où PUT est utilisé pour remplacer la ressource produit complète.
Produit initial :
| GET /products/1001{"id": 1001, "name": "Laptop", "price": 999,99, "description": "Un ordinateur portable puissant."} |
Vous souhaitez mettre à jour le prix et la description du produit. Vous envoyez une requête PUT avec l'intégralité de la ressource :
Demande PUT :
| PUT /products/1001{"id": 1001, "name": "Laptop", "price": 899,99, "description": "Un ordinateur portable puissant à prix réduit."} |
Si vous effectuez cette requête PUT une ou plusieurs fois, le résultat sera toujours le même. Les détails du produit seront mis à jour pour refléter le nouveau prix et la nouvelle description, et le même résultat se produira à chaque fois. Cela garantit la nature idempotente de PUT.
Résultat (après demande PUT) :
| {"id": 1001, "name": "Laptop", "price": 899,99, "description": "Un ordinateur portable puissant à prix réduit."} |
Scénario 2 : Requête PATCH – Mise à jour d'une partie d'une ressource
Considérons maintenant une demande PATCH pour mettre à jour uniquement une partie des détails du produit, comme la description. Exemple d'API PATCH : Si vous souhaitez modifier la description du produit mais pas son prix, PATCH est le meilleur choix. Pour implémenter cela, vous devez créer des correctifs contenant uniquement les champs nécessitant une modification, comme la description dans cet exemple API REST PATCH.
Produit initial :
| GET /products/1001{"id": 1001, "name": "Laptop", "price": 999,99, "description": "Un ordinateur portable puissant."} |
Demande de PATCH :
| PATCH /products/1001{« description » : « Un ordinateur portable léger et puissant. »} |
Lorsque vous envoyez cette demande PATCH, seul le champ de description sera mis à jour. Si vous envoyez plusieurs fois la même requête PATCH, la description restera inchangée après la première mise à jour, rendant la requête idempotente.
Résultat (après demande PATCH) :
| {"id": 1001, "name": "Laptop", "price": 999,99, "description": "Un ordinateur portable léger et puissant."} |
Si vous appliquez à nouveau le même PATCH, la description du produit sera toujours la même qu'après le premier PATCH. Le résultat est cohérent, ce qui rend PATCH idempotent dans ce scénario.
Scénario 3 : Demande PATCH – Opération non idempotente
Regardons une opération PATCH non idempotente. Supposons qu’il existe un point final pour le solde du portefeuille d’un utilisateur et que vous souhaitiez augmenter le solde. Un exemple de différence entre PUT et PATCH peut être illustré ici : PATCH ajoutera une valeur au solde à chaque fois.
Portefeuille initial :
| GET /users/1/wallet{"id": 1, "solde": 100,00} |
Demande de PATCH :
| PATCH /users/1/wallet{« incrément » : 50,00} |
Cette demande PATCH augmentera le solde du portefeuille de 50 $. Si vous envoyez cette requête PATCH plusieurs fois, le solde continuera d'augmenter avec chaque PATCH, conduisant à un résultat différent à chaque fois. Ceci n’est pas idempotent car l’application répétée du même PATCH entraînera un résultat différent.
Résultat (après la première demande PATCH) :
| {"id": 1, "solde": 150,00} |
Résultat (après la deuxième demande PATCH) :
| {"id": 1, "solde": 200,00} |
Ici, PATCH n'est pas idempotent car des requêtes répétées avec les mêmes données produisent des résultats différents.
Récapitulatif : principales différences entre PUT et PATCH dans les API REST
La principale différence entre PUT et PATCH dans l'API REST réside dans la façon dont ils gèrent les mises à jour. PUT remplace la totalité de la ressource, de sorte que tous les champs manquants sont effacés, ce qui peut entraîner une perte de données. C'est pourquoi les développeurs créent des correctifs pour les mises à jour partielles, afin d'éviter d'écraser les champs inchangés et de maintenir l'intégrité des données.
Cela rend PATCH plus efficace pour les mises à jour partielles. Un exemple d'API PATCH est le suivant : si vous souhaitez mettre à jour uniquement l'e-mail d'un utilisateur, la création de correctifs n'enverrait que le champ d'e-mail, contrairement à une requête PUT qui nécessiterait l'intégralité des données utilisateur.
Avec PUT, la charge utile complète des données est requise. Cela signifie que chaque champ doit être envoyé et que tous les champs manquants seront effacés. Cependant, PATCH n'envoie que les champs qui doivent être mis à jour, ce qui le rend plus efficace, en particulier pour les ressources volumineuses avec des modifications minimes. La méthode PATCH dans l'API REST permet des requêtes plus ciblées et plus petites, réduisant ainsi le transfert de données.
PUT et PATCH sont idempotents. Cela signifie que répéter la même demande entraînera le même résultat. Cependant, PUT est plus prévisible car il remplace la totalité de la ressource. PATCH, lorsqu'il est utilisé pour modifier uniquement les champs spécifiés, peut conduire à des résultats différents selon la façon dont les mises à jour sont gérées par le serveur.
Par exemple, si un PATCH incrémente un compteur, des requêtes répétées pourraient conduire à des résultats différents. Néanmoins, les opérations de l'API PATCH peuvent également être conçues pour être idempotentes.
En conclusion, la différence entre PUT et PATCH dans l'API REST se résume à la nature des mises à jour : PATCH concerne les modifications partielles, tandis que PUT concerne le remplacement complet des ressources. Les deux sont idempotents, mais PATCH peut être plus complexe.
Pensées finales
PUT et PATCH sont des méthodes HTTP fondamentales dans la conception de l'API REST, mais elles servent des objectifs différents, ce qui constitue l'essence de la différence PUT et PATCH dans l'API REST. Vous pouvez améliorer considérablement l'efficacité, la clarté et les fonctionnalités de votre API en comprenant la différence entre PUT et PATCH avec les exemples que nous avons abordés plus tôt dans cet article. En choisissant la bonne méthode (PATCH ou mise à jour REST) en fonction de votre cas d'utilisation, vous pouvez rendre votre API plus efficace, plus maintenable et plus conviviale. Tenez toujours compte de la nature de la mise à jour, qu'elle soit complète ou partielle, ainsi que de son impact sur les performances et l'intégrité des données, et sélectionnez la méthode la mieux adaptée à vos besoins.
