Concevoir une API RESTful conforme aux conventions

1. Qu'est-ce qu'une API REST ? Les fondations

Avant de plonger dans les détails, assurons-nous de partager un vocabulaire commun. REST (Representational State Transfer) n'est pas une technologie, mais un style d'architecture qui définit un ensemble de contraintes pour la création de services web.

La vidéo suivante offre une excellente introduction aux concepts fondamentaux d'une API et à l'architecture REST.

Pour résumer, une API RESTful est une interface qui :

• S'organise autour des ressources (des "choses", comme des utilisateurs, des produits, des commandes).
• Utilise des identifiants uniques (URIs) pour accéder à ces ressources.
• Communique via le protocole HTTP standard, en exploitant ses méthodes (verbes) et ses codes de statut.
• Est sans état (stateless) : chaque requête du client doit contenir toutes les informations nécessaires pour être comprise par le serveur, sans que ce dernier ait besoin de se souvenir des requêtes précédentes.

2. Les piliers d'une conception RESTful

Une API bien conçue repose sur le respect de conventions claires. Nous allons nous concentrer sur les trois plus importantes : le nommage des URIs, l'utilisation des verbes HTTP et le retour de codes de statut appropriés.

2.1. Nommage des ressources : les URIs

La règle d'or est simple : une URI identifie une ressource (un nom), pas une action (un verbe). L'action sera définie par le verbe HTTP utilisé.

Pour approfondir ces conventions de nommage, je vous propose de lire deux ressources complémentaires. La première, de Microsoft, est une référence technique, et la seconde, du blog OCTO, offre une perspective pragmatique.

Synthèse des conventions de nommage des URIs :

• Utilisez des noms, pas des verbes.
  • Bien : GET /orders/123
  • À éviter : GET /getOrderById?id=123
• Utilisez des noms au pluriel pour les collections.
  • /users, /products, /clients
• Utilisez le format /collection/{id} pour un élément spécifique.
  • /users/42 : pour récupérer l'utilisateur avec l'ID 42.
• Pour les ressources imbriquées, suivez la hiérarchie.
  • /clients/3/orders : pour lister toutes les commandes du client 3.
• Soyez cohérent avec la casse. Le spinal-case (ex: ma-ressource) est courant, tout comme le snake_case (ma_ressource). Le plus important est de choisir un style et de s'y tenir.

2.2. Choisir la bonne action : les verbes HTTP

Maintenant que nos URIs identifient les ressources, nous utilisons les verbes (ou méthodes) HTTP pour dire ce que nous voulons faire avec elles. Cela correspond aux opérations CRUD (Create, Read, Update, Delete) que vous connaissez.

Le tableau suivant, tiré de l'article d'OCTO, est un résumé parfait de la manière de mapper ces opérations.

Synthèse des verbes HTTP :

Une opération est idempotente si le fait de l'appeler plusieurs fois de suite avec les mêmes paramètres a le même effet que de l'appeler une seule fois. Par exemple, supprimer un utilisateur avec DELETE /users/42 une fois ou dix fois donne le même résultat final : l'utilisateur 42 n'existe plus.

2.3. Communiquer le résultat : les codes de statut HTTP

Une fois que le serveur a traité la requête, il doit informer le client du résultat. C'est le rôle des codes de statut HTTP. Utiliser le bon code est essentiel pour que le client puisse réagir de manière appropriée (afficher un succès, une erreur, tenter de se ré-authentifier, etc.).

Les articles de Microsoft et d'OCTO que vous avez consultés contiennent des listes détaillées de ces codes.

Les codes de statut essentiels :

• Succès (2xx)
  • 200 OK : Succès général pour GET, PUT, PATCH.
  • 201 Created : La ressource a été créée avec succès (POST). La réponse doit inclure un en-tête Location avec l'URI de la nouvelle ressource.
  • 204 No Content : Succès, mais il n'y a pas de contenu à renvoyer (souvent pour DELETE).
• Erreur client (4xx)
  • 400 Bad Request : La requête du client est malformée (ex: JSON invalide, paramètre manquant).
  • 401 Unauthorized : Le client doit s'authentifier pour accéder à la ressource.
  • 403 Forbidden : Le client est authentifié mais n'a pas les droits pour effectuer cette action.
  • 404 Not Found : La ressource demandée n'existe pas.
• Erreur serveur (5xx)
  • 500 Internal Server Error : Une erreur inattendue s'est produite côté serveur.

3. De la théorie à la pratique avec Spring Boot

Comment ces principes se traduisent-ils en code dans un projet Spring Boot ? L'écosystème Spring nous fournit des annotations qui correspondent directement à ces conventions.

La vidéo suivante est un tutoriel complet de création d'une application CRUD. Nous n'allons pas la suivre en entier, mais nous allons l'utiliser comme une référence pour voir comment les conventions REST sont implémentées.

Cette vidéo illustre parfaitement l'architecture cible de nos APIs :

Conclusion

Aujourd'hui, nous avons posé les fondations indispensables à la création d'APIs REST professionnelles. En respectant ces conventions, vous ne vous facilitez pas seulement la vie, vous créez surtout des services que d'autres développeurs pourront comprendre et utiliser intuitivement.

Les points clés à retenir :

1. URIs avec des Noms : Les URIs représentent des ressources (noms, au pluriel) et leur hiérarchie (/clients, /clients/{id}).
2. Actions avec des Verbes HTTP : GET pour lire, POST pour créer, PUT/PATCH pour mettre à jour, DELETE pour supprimer.
3. Résultats avec des Codes de Statut : Utilisez les codes HTTP (2xx, 4xx, 5xx) pour communiquer clairement le résultat de chaque opération.
4. Spring Boot facilite l'implémentation de ces conventions grâce à des annotations dédiées (@RestController, @GetMapping, @PostMapping, ResponseEntity, etc.).

Dans la prochaine leçon, nous mettrons tout cela en pratique. L'objectif sera d'implémenter les opérations CRUD complètes pour une ressource, en créant vous-même un Controller qui respecte scrupuleusement les principes vus aujourd'hui. Préparez-vous à coder