Les API REST vous permettent de développer tout type d’application web ayant toutes les opérations CRUD (créer, récupérer, mettre à jour, supprimer) possibles. Les directives REST suggèrent d’utiliser une méthode HTTP spécifique sur un type particulier d’appel fait au serveur (bien que techniquement il soit possible de violer cette directive, cependant c’est fortement déconseillé).
Utilisez les informations données ci-dessous pour trouver une méthode HTTP appropriée pour l’action effectuée par l’API.
Table of ContentsHTTP GETHTTP POSTHTTP PUTHTTP DELETEHTTP PATCHSummaryGlossary
HTTP GET
Utilisez les requêtes GET pour récupérer la représentation de la ressource/l’information seulement – et non pour la modifier de quelque façon que ce soit. Comme les requêtes GET ne modifient pas l’état de la ressource, on dit que ce sont des méthodes sûres. En outre, les API GET doivent être idempotentes, ce qui signifie que le fait d’effectuer plusieurs requêtes identiques doit produire le même résultat à chaque fois jusqu’à ce qu’une autre API (POST ou PUT) ait modifié l’état de la ressource sur le serveur.
Si la Request-URI fait référence à un processus de production de données, ce sont les données produites qui doivent être renvoyées comme entité dans la réponse et non le texte source du processus, à moins que ce texte ne se trouve être la sortie du processus.
Pour toute API HTTP GET donnée, si la ressource est trouvée sur le serveur, alors elle doit renvoyer le code de réponse HTTP 200 (OK) – ainsi que le corps de réponse, qui est généralement un contenu XML ou JSON (en raison de leur nature indépendante de la plateforme).
Dans le cas où la ressource n’est PAS trouvée sur le serveur, alors elle doit renvoyer le code de réponse HTTP 404 (NOT FOUND). De même, s’il est déterminé que la requête GET elle-même n’est pas correctement formée alors le serveur doit retourner le code de réponse HTTP 400 (BAD REQUEST).
Exemple de requête URI
- HTTP GET http://www.appdomain.com/users
- HTTP GET http://www.appdomain.com/users ?size=20&page=5
- HTTP GET http://www.appdomain.com/users/123
- HTTP GET http://www.appdomain.com/users/123/adresse
HTTP POST
Utiliser les API POST pour créer de nouvelles ressources subordonnées, par ex, un fichier est subordonné à un répertoire qui le contient ou une ligne est subordonnée à une table de base de données. Lorsqu’on parle strictement en termes de REST, les méthodes POST sont utilisées pour créer une nouvelle ressource dans la collection de ressources.
En principe, si une ressource a été créée sur le serveur d’origine, la réponse DEVRAIT être un code de réponse HTTP 201 (Created) et contenir une entité qui décrit l’état de la demande et fait référence à la nouvelle ressource, ainsi qu’un en-tête Location.
Plusieurs fois, l’action exécutée par la méthode POST pourrait ne pas donner lieu à une ressource qui peut être identifiée par une URI. Dans ce cas, le code de réponse HTTP 200 (OK) ou 204 (No Content) est le statut de réponse approprié.
Les réponses à cette méthode ne peuvent pas être mises en cache, à moins que la réponse n’inclue les champs d’en-tête Cache-Control ou Expires appropriés.
Veuillez noter que POST n’est ni sûr ni idempotent, et invoquer deux requêtes POST identiques donnera lieu à deux ressources différentes contenant les mêmes informations (à l’exception des ids de ressources).
Exemple de requête URI
- HTTP POST http://www.appdomain.com/users
- HTTP POST http://www.appdomain.com/users/123/accounts
HTTP PUT
Utiliser les API PUT principalement pour mettre à jour une ressource existante (si la ressource n’existe pas, alors l’API peut décider de créer une nouvelle ressource ou non). Si une nouvelle ressource a été créée par l’API PUT, le serveur d’origine DOIT informer l’agent utilisateur via le code de réponse HTTP 201 (Created) réponse et si une ressource existante est modifiée, les codes de réponse 200 (OK) ou 204 (No Content) DOIVENT être envoyés pour indiquer la réussite de la demande.
Si la demande passe par un cache et que la Request-URI identifie une ou plusieurs entités actuellement en cache, ces entrées DOIVENT être traitées comme stale. Les réponses à cette méthode ne peuvent pas être mises en cache.
Exemple d’URI de requête
- HTTP PUT http://www.appdomain.com/users/123
- HTTP PUT http://www.appdomain.com/users/123/accounts/456
HTTP DELETE
Comme son nom l’indique, les API DELETE sont utilisées pour supprimer des ressources (identifiées par la Request-URI).
Une réponse réussie des demandes DELETE DEVRAIT être la réponse HTTP code 200 (OK) si la réponse comprend une entité décrivant l’état, 202 (Accepted) si l’action a été mise en file d’attente, ou 204 (No Content) si l’action a été exécutée mais que la réponse ne comprend pas d’entité.
Les opérations DELETE sont idempotentes. Si vous DELETEz une ressource, elle est retirée de la collection de ressources. L’appel répété de l’API DELETE sur cette ressource ne changera pas le résultat – cependant, l’appel DELETE sur une ressource une deuxième fois renverra un 404 (NOT FOUND) puisqu’elle a déjà été supprimée. Certains diront que cela rend la méthode DELETE non-idempotente. C’est une question de discussion et d’opinion personnelle.
Si la requête passe par un cache et que la Request-URI identifie une ou plusieurs entités actuellement mises en cache, ces entrées DEVRAIENT être traitées comme étant périmées. Les réponses à cette méthode ne peuvent pas être mises en cache.
Exemple d’URI de requête
- HTTP DELETE http://www.appdomain.com/users/123
- HTTP DELETE http://www.appdomain.com/users/123/accounts/456
HTTP PATCH
Les requêtes HTTP PATCH sont pour faire une mise à jour partielle sur une ressource. Si vous voyez que les demandes PUT modifient également une entité de ressource, donc pour être plus clair – la méthode PATCH est le choix correct pour la mise à jour partielle d’une ressource existante, et PUT ne devrait être utilisé que si vous remplacez une ressource dans son intégralité.
Veuillez noter qu’il y a quelques défis si vous décidez d’utiliser les API PATCH dans votre application :
- Le support de PATCH dans les navigateurs, les serveurs et les cadres d’applications web n’est pas universel. IE8, PHP, Tomcat, Django, et beaucoup d’autres logiciels ont un support manquant ou cassé pour cela.
- La charge utile d’une requête PATCH n’est pas simple comme pour une requête PUT. par ex.
HTTP GET /users/1produit la réponse ci-dessous:
{id: 1, username: 'admin', email: ''}Un exemple de demande de patch pour mettre à jour l’email sera comme ceci:
HTTP PATCH /users/1» }
]
Il peut y avoir les opérations possibles suivantes sont selon la spécification HTTP.
},
{ "op": "replace", "path": "/a/b/c", "value": 42 },
{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" },
{ "op": "copy","from": "/a/b/d", "path": "/a/b/e" }
]
La méthode PATCH ne remplace pas les méthodes POST ou PUT. Elle applique un delta (diff) plutôt que de remplacer l’ensemble de la ressource.
Résumé des méthodes HTTP pour les API RESTful
Le tableau ci-dessous résume l’utilisation des méthodes HTTP discutées ci-dessus.
| Méthode HTTP | CRUD | Entire Collection (par ex. /users) | Elément spécifique (par exemple /users/123) |
|---|---|---|---|
| POST | Create | 201 (Créé), en-tête ‘Emplacement’ avec lien vers /users/{id} contenant le nouvel identifiant. | Éviter d’utiliser POST sur une ressource unique |
| GET | Read | 200 (OK), liste des utilisateurs. Utilisez la pagination, le tri et le filtrage pour naviguer dans les grandes listes. | 200 (OK), utilisateur unique. 404 (Not Found), si l’ID n’est pas trouvé ou invalide. |
| PUT | Update/Replace | 405 (Méthode non autorisée), sauf si vous voulez mettre à jour chaque ressource dans la collection entière de ressource. | 200 (OK) ou 204 (No Content). Utilisez 404 (Not Found), si l’ID est introuvable ou invalide. |
| PATCH | Mise à jour partielle/Modification | 405 (Méthode non autorisée), sauf si vous voulez modifier la collection elle-même. | 200 (OK) ou 204 (No Content). Utilisez 404 (Not Found), si l’ID n’est pas trouvé ou invalide. |
| DELETE | Delete | 405 (Méthode non autorisée), à moins que vous ne vouliez supprimer toute la collection – à utiliser avec prudence. | 200 (OK). 404 (Not Found), si l’ID n’a pas été trouvé ou n’est pas valide. |
Glossaire
Méthodes sûres
Selon la spécification HTTP, les méthodes GET et HEAD doivent être utilisées uniquement pour récupérer les représentations de la ressource – et elles ne mettent pas à jour/supprimer la ressource sur le serveur. Ces deux méthodes sont dites « sûres ».
Cela permet aux agents utilisateurs de représenter d’autres méthodes, telles que POST, PUT et DELETE, d’une manière unique afin que l’utilisateur soit informé du fait qu’une action possiblement non sûre est demandée – et elles peuvent mettre à jour/supprimer la ressource sur le serveur et doivent donc être utilisées avec précaution.
Méthodes idempotentes
Le terme idempotent est utilisé de manière plus complète pour décrire une opération qui produira les mêmes résultats si elle est exécutée une ou plusieurs fois. L’idempotence est une propriété pratique dans de nombreuses situations, car elle signifie qu’une opération peut être répétée ou réessayée aussi souvent que nécessaire sans provoquer d’effets inattendus. Avec les opérations non idempotentes, l’algorithme peut avoir à garder la trace du fait que l’opération a déjà été exécutée ou non.
Dans la spécification HTTP, Les méthodes GET, HEAD, PUT et DELETE sont déclarées idempotentes. Les autres méthodes OPTIONS et TRACE NE DEVRAIENT PAS avoir d’effets secondaires, donc les deux sont aussi intrinsèquement idempotentes.