Spécification REST

La spécification REST normalise la forme d’appel des webservices; elle s’appuie sur la notion de ressources.

Exemple : la ressource users associée au end-point https://rest.jcbuisson.dev/api/users

• chaque instance de ressource (par ex. chaque user) possède un identifiant
• les verbes HTTP GET, POST, PUT et DELETE correspondent à des opérations de type CRUD (CREATE, READ, UPDATE, and DELETE) sur les ressources

GET : lit une ou plusieurs ressources.

Exemples :

Les deux requêtes font référence au end-point https://rest.jcbuisson.dev/api/users ; la première demande la liste de tous les utilisateurs, la seconde la liste de tous les utilisateurs hommes, la troisième l’utilisateur d’identifiant 1.

POST : créé une nouvelle ressource.

Exemple :

Cette requête créée une nouvelle resource pour le endpoint https://rest.jcbuisson.dev/api/users, c’est à dire un nouvel utilisateur. Les données qui concernent l’utilisateur doivent être placées dans la section DATA de la requête.

curl -X POST -H 'Content-Type: application/json' -d '{"firstname": "John", "lastname": "Doe"}' https://rest.jcbuisson.dev/api/users

PUT : modifie complétement une ressource.

Exemple :

L’ensemble des données de l’utilisateur 1 doit être placé dans la section DATA de la requête.

curl -X PUT -H 'Content-Type: application/json' -d '{"firstname": "Jon", "lastname": "Doe"}' https://rest.jcbuisson.dev/api/users/1

PATCH : modifie en partie une ressource.

Exemple :

À la différence de PUT, seules les données à modifier doivent être placées dans la section DATA de la requête

curl -X PATCH -H 'Content-Type: application/json' -d '{"firstname": "Joe"}' https://rest.jcbuisson.dev/api/users/1

DELETE : supprime une ressource.

Example:

Remarque : on ne peut supprimer qu’un seul élément par appel

HEAD

HEAD est similaire à GET, mais ne renvoie que les headers et pas la réponse

OPTIONS

OPTIONS est utilisée pour obtenir les options de communication avec la cible : verbes HTTP possibles, méthodes d’authentification demandées, utilisation de la politique CORS (Cross Origin Resource Sharing). (voir ‘preflight requests’)

Remarque : la spécification REST est aussi applicable au transport Websocket