Nommer nos endPoints quand on fait du Rest

Mais Qu'est ce que REST ?

Contrairement à ce qu'on entend souvent, REST n'est pas un protocole !!!!!!!!!!!!!! Le REST est un style d'architecture utilisé pour communiquer avec des services web. Néanmoins, cette communication est basée sur un protocole très connu dans le monde du web, le protocole HTTP ( Hypertext Transfert Protocol).

Aujourd'hui, le REST est certainement le style d'architecture le plus utilisé pour communiquer avec les services web. Et de ma petite expérience, j'ai vu beaucoup de collègues développeurs me vendre "oui on fait du REST, voir du RestFul" parce qu'ils avaient des ressources exposées via des endpoints. Cela suffit t-il

Pour illustrer comment nommer nos endpoints, on va supposer que la gestion d'une bibliothèque de musique nous a été confiée. On va donc devoir designer une API REST pour cela.

Besoins

Nous allons offrir à travers notre API, un moyen de: créer, récupérer,modifier et supprimer un album. Ces quatres opérations citées sont appelées CRUD (Create Read Update Delete).

Rappelez vous, on a dit que la communication est basée sur le protocole HTTP. En effet, ce protocole offre ce qu'on appelle des méthodes HTTP. Parmi ces méthodes, figurent POST, GET, PUT, DELETE, PATCH. Vous pouvez retrouver la liste complète en cliquant sur ce lien https://developer.mozilla.org/fr/docs/Web/HTTP/M%C3%A9thode.

POST api/albums (plus corps de la requête ) : Permettra de créer, grâce aux informations fournies dans le corps de la requête, une nouvelle ressource. Dans notre cas, un nouvel album. Cette création aura pour effet d'attribuer un id unique à l'album créé.

GET api/albums : Permettra de récupérer tous les albums figurant dans notre bibliothèque.

GET api/albums/2 : Permettra de récupérer un seul album, celui ayant l'identifiant 2. (2 n'est qu'un exemple)

PUT api/albums/3 (plus corps de la requête) : Permettra de modifier l'album correspondant à l'identifiant 3 avec les informations fournies dans le corps de la requête

DELETE api/albums/ 1 : Permettra de supprimer de notre bibliothèque, l'album ayant l'identifiant 1.

Toutes ces opérations doivent systématiquement retournées un code. Ce code est un ensemble de nombres définis par le protocole HTTP. Ces codes permettent au client qui consomme notre API de connaître comment s'est passé l'opération. Le plus connu de ces codes est certainement le 404 . Il indique au client que la source demandée est inexistante. Vous retrouverez la liste Complète des codes http sur ce lien https://developer.mozilla.org/fr/docs/Web/HTTP/Status.

Il est important de souligner que jamais nos endpoints ne déterminent l'action réalisée. On a jamais par exemple api/albums/ addpour ajouter, ou api/albums/ deletepour supprimer car c'est aux methodes HTTP de déterminer l'action réalisée.

Dans un prochain tuto, nous allons implémenter notre bibliothèque avec Java Spring. Vous pouvez d'ores et déjà retrouver le code à cette adresse : https://gitlab.com/yourexperimentation/crudexamplespring.git