REST API

Table des matières

1. Méthodes

1.1. GET

GET permet de retrouver un enregistrement.

GET /users/5 retournera la fiche de cet utilisateur.

En aucune manière, GET ne peut modifier quoi que ce soit sur le serveur web. GET /users/delete/1 est donc plusieurs fois incorrecte; il faut utiliser la méthode DELETE, GET tel qu’utilisé ici demande à supprimer quelque chose, l’appel à ce supposé GET /users/delete/1 n’aurait pas la même réponse (suppression la première fois, message d’erreur utilisateur inconnu les autres fois).

1.2. POST

Exemple : formulaire de création d’un enregistrement (un todo, une note, une réclamation, ...). Si on poste le formulaire plusieurs fois, on va créer plusieurs enregistrements dans la base de données.

Au niveau de la base de données, on obtiendra plusieurs records avec des IDs différents.

Avec POST, par définition, on ne connaît pas l’ID du record.

POST /users/5 est donc impossible ⇒ dès qu’on connaît l’ID, il faut utiliser PUT /users/5 et toutes les données de l’utilisateur.

POST /users crée une nouvelle fiche utilisateur.

1.3. PUT

Simlar to POST, PUT requests are used to send data to the API to create or update a resource.

PUT est utilisé pour créer un enregistrement (on obtient alors son ID) et pour le mettre à jour. Lorsqu’on appelle plusieurs fois la même requête avec un PUT, le résultat est strictement le même : la mise-à-jour concernera toujours le même enregistrement.

Avec PUT il faut envoyer tous les champs qui composent l’enregistrement; même ceux n’ayant pas été modifié.

PUT /users/5 met à jour toutes les données de cet utilisateur.

PUT ou POST ? Pour créer un enregistrement sur le serveur, si on connaît l’ID lors de la requête, on peut faire un PUT /contract/789 càd qu’on définit nous-même, à l’appel, l’ID à créer. Si on laisse le soin au serveur de définir lui-même l’ID alors on fera POST /contract/create.

1.4. PATCH

Similaire à PUT, PATCH est à utiliser lorsqu’on envoie au serveur uniquement les champs à adapter (si on ne change que le titre, il ne faut pas envoyer les autres champs comme description, auteur, dates, ...).

PATCH /users/5 avec comme donnée {"email"="valeur"} pour mettre à jour cette seule information.

1.5. DELETE

Supprime la ressource identifiée.

DELETE /users/5 pour supprimer cet utilisateur

1.6. HEAD

Identique à GET excepté que le serveur n’envoie pas de réponse excepté un code HTTP

HEAD /users/5 qui permettra de vérifier si cet utilisateur existe et retournera un code HTTP selon que ce soit le cas ou pas.

HEAD /tres_gros_fichier.zip ne sert qu’à vérifier l’existence du fichier là où GET sur la même ressource aurait pour conséquence de télécharger le fichier.

1.7. OPTIONS

OPTIONS demande au serveur quelles sont les méthodes autorisées pour la ressource mentionnée.

OPTIONS /users/5 pourrait retourner juste GET pour signifier qu’on peut consulter la fiche de l’utilisateur mais pas la modifier.

1.8. CONNECT

Cette méthode permet d’utiliser un proxy comme un tunnel de communication. (source wikipédia)

1.9. TRACE

Cette méthode demande au serveur de retourner ce qu’il a reçu, dans le but de tester et effectuer un diagnostic sur la connexion. (source wikipédia)

1.10. Summary

https://www.restapitutorial.com/lessons/httpmethods.html

HTTP Verb CRUD Entire Collection (e.g. /customers) Specific Item (e.g. /customers/{id})
POST Create 201 (Created), 'Location’ header with link to /customers/{id} containing new ID. 404 (Not Found), 409 (Conflict) if resource already exists..
GET Read 200 (OK), list of customers. Use pagination, sorting and filtering to navigate big lists. 200 (OK), single customer. 404 (Not Found), if ID not found or invalid.
PUT Update/Replace 405 (Method Not Allowed), unless you want to update/replace every resource in the entire collection. 200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.
PATCH Update/Modify 405 (Method Not Allowed), unless you want to modify the collection itself. 200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.
Delete Delete 405 (Method Not Allowed), unless you want to delete the whole collection—not often desirable. 200 (OK). 404 (Not Found), if ID not found or invalid

1.11. Lire plus

2. Outils pour tester des API

Insomnia (pas encore testé) est une interface disponible pour différents environnements (Mac, PC, ...) et permet d’aisément tester des appels à des APIs.

https://github.com/getinsomnia/insomnia