Chapitre 03 — Comment les API sont conçues5 min de lecture

REST : les conventions de nommage

Vous connaissez déjà REST

Voici le secret : tout ce que vous avez fait dans ce cours jusqu'à présent ? C'était du REST.

Chaque URL que vous avez appelée (/users, /users/1, /products), chaque méthode que vous avez utilisée (GET, POST, PUT, DELETE), chaque réponse JSON que vous avez lue. Tout cela suit un ensemble de conventions appelé REST (Representational State Transfer).

REST n'est pas une technologie. Ce n'est pas un protocole. C'est un guide de style. Un ensemble de conventions de nommage que la plupart des API suivent pour que les développeurs (et maintenant vous) puissent prédire le fonctionnement d'une API sans avoir à mémoriser chaque endpoint.

Les deux modèles d'URL

REST se résume à deux modèles d'URL. Seulement deux :

Modèle 1 : la collection. /users, /products, /orders. Cela pointe vers la table entière. Tous les utilisateurs, tous les produits, tous les ordres.

Modèle 2 : un élément spécifique. /users/1, /products/42, /orders/789. Cela pointe vers une seule ligne de la table, identifiée par son ID.

GET/products → tous les produits (la collection)
GET/products/42 → un produit (un élément spécifique)
MéthodeChemin

C'est la base. Tout le reste dans REST est construit sur ces deux modèles.

La matrice CRUD complète

Combinez les deux modèles d'URL avec les quatre méthodes HTTP, et vous obtenez le manuel complet :

GET/products → lister tous les produits
GET/products/42 → obtenir le produit n°42
POST/products → créer un nouveau produit
PUT/products/42 → mettre à jour le produit n°42
DELETE/products/42 → supprimer le produit n°42
MéthodeChemin

Cinq lignes. C'est tout le manuel REST pour n'importe quelle ressource. Si vous connaissez le nom de la ressource, vous connaissez les endpoints.

Remarquez la logique : POST s'adresse à la collection (/products) parce que vous ajoutez un élément au groupe. PUT et DELETE s'adressent à un élément spécifique (/products/42) parce que vous modifiez ou supprimez une ligne particulière.

La prévisibilité est le but

La seule raison d'être des conventions REST est la prévisibilité. Si une API a un endpoint /users, vous pouvez deviner :

  • GET /users vous donne la liste des utilisateurs.
  • GET /users/5 vous donne l'utilisateur n°5.
  • POST /users crée un nouvel utilisateur.
  • PUT /users/5 met à jour l'utilisateur n°5.
  • DELETE /users/5 supprime l'utilisateur n°5.

Vous n'avez pas besoin de lire la doc pour deviner cela. C'est la force des conventions. C'est comme conduire dans une ville étrangère : vous n'y êtes jamais allé, mais vous savez que le rouge signifie s'arrêter et le vert démarrer.

Vérifions. DummyJSON suit les conventions REST. Essayez d'obtenir la liste des produits :

GEThttps://dummyjson.com/products?limit=2&select=id,title,price,category

Maintenant, un produit spécifique par son ID :

GEThttps://dummyjson.com/products/1?select=id,title,price,category

Même URL de base, même nom de ressource. Le modèle fonctionne exactement comme prévu.

Les règles de nommage

REST a quelques conventions de nommage qui assurent la cohérence :

Utilisez des noms au pluriel. /users, pas /user. /products, pas /product. L'endpoint représente la collection (la table), et les tables contiennent plusieurs éléments.

Utilisez des noms, pas des verbes. L'URL décrit ce que vous manipulez, pas ce que vous faites. La méthode HTTP se charge de l'action.

DELETE/users/42 → correct
POST/users/42/delete → incorrect
MéthodeChemin

Le premier est RESTful. La méthode (DELETE) dit quoi faire, le chemin (/users/42) dit sur quoi le faire. Une séparation nette.

Le second intègre l'action dans l'URL. C'est redondant et casse la convention. Si vous voyez des URL comme /createUser ou /deleteProduct/42 dans une API, cette API ne suit pas les conventions REST.

Gardez les URL en minuscules. /users/42, pas /Users/42.

Ce que signifie "RESTful"

Vous entendrez des ingénieurs dire "notre API est RESTful" ou "ce n'est pas très RESTful". Maintenant, vous savez ce qu'ils veulent dire.

RESTful = l'API suit les conventions REST. Des noms au pluriel dans les URL, des méthodes HTTP standard pour le CRUD, des modèles d'URL prévisibles. Cela ne signifie pas que l'API est parfaite ou puissante. Cela signifie qu'elle suit le guide de style.

La plupart des API avec lesquelles vous travaillerez sont RESTful. Certaines ne le sont pas (GraphQL est une approche différente, par exemple). Mais REST est le standard par défaut, la lingua franca. C'est ce que les ingénieurs supposent, sauf indication contraire.

Points clés à retenir

  • REST est un ensemble de conventions de nommage, pas une technologie.
  • Deux modèles d'URL : /choses (collection) et /choses/id (élément spécifique).
  • Combinez-les avec GET, POST, PUT, DELETE pour obtenir le manuel CRUD complet.
  • Les URL utilisent des noms au pluriel (/users, pas /user) et aucun verbe (DELETE /users/42, pas POST /users/42/delete).
  • RESTful signifie que l'API suit ces conventions. La plupart des API le font.