Définir le contrat des ressources
Objectif : Associer chaque opération sur les commandes et les produits à une méthode et une URL HTTP, puis choisir un code de statut cohérent.
Une API devient difficile à utiliser lorsque deux opérations différentes partagent une URL sans règle claire, ou lorsque la même action change de méthode selon la ressource. Vous allez fixer un contrat HTTP lisible pour les commandes et les produits avant d’ajouter des routes Express. Ce contrat précise les méthodes, les chemins et le résultat attendu de chaque opération.
Votre serveur Express et son port configurable sont déjà en place, comme vu dans « Initialiser le serveur Express ». À ce stade, vous définissez la convention des ressources ; vous ne créez pas encore les routeurs, ne lisez pas les corps de requête et ne formatez pas les réponses JSON, qui seront traités dans les leçons suivantes.
Une URL représente une ressource
Une ressource désigne une catégorie de données gérée par l’API. Dans le projet, les deux collections principales sont /api/commandes et /api/produits. Les chemins sont des noms au pluriel : ils identifient les données, tandis que la méthode HTTP indique l’action demandée.
Pour viser un élément précis, vous ajouterez son identifiant au chemin : par exemple, /api/commandes/42. La signification détaillée des paramètres de route et des paramètres de requête sera abordée dans « Lire les requêtes et formater les réponses » ; ici, retenez seulement la convention de chemin. Les filtres d’une liste, eux, resteront associés à la collection des commandes et seront portés par des paramètres de requête dans une leçon ultérieure.
Associer une méthode à une opération
GET sert à consulter une collection ou un élément sans demander sa modification. POST, envoyé à la collection, demande la création d’un nouvel élément ; PATCH, adressé à un élément identifié, demande une modification partielle. Enfin, DELETE sur un élément demande sa suppression.
| Méthode et chemin | Opération attendue | Résultat usuel |
|---|---|---|
| GET /api/commandes | Lister les commandes ; la liste pourra être filtrée | 200 OK |
| GET /api/commandes/42 | Consulter la commande 42 | 200 OK ou 404 Not Found |
| POST /api/commandes | Créer une commande | 201 Created |
| PATCH /api/commandes/42 | Modifier partiellement la commande 42 | 200 OK ou 404 Not Found |
| DELETE /api/commandes/42 | Supprimer la commande 42 | 204 No Content ou 404 Not Found |
| GET /api/produits | Lister les produits disponibles | 200 OK |
| GET /api/produits/7 | Consulter le produit 7 | 200 OK ou 404 Not Found |
Ce tableau est le contrat de départ du service : chaque combinaison méthode-chemin désigne une opération sans ambiguïté. Il est cohérent avec la page de documentation fournie dans le projet, qui présente déjà la liste des commandes, la création d’une commande et la liste des produits. Les opérations sur un produit sont définies ici pour garder un contrat prévisible, même si leur implémentation viendra dans le parcours.
Lire le contrat dans des exemples
Une requête de création vise la collection, et non un identifiant qui n’existe pas encore. Le serveur répond par 201 Created si la commande est créée ; le corps envoyé et le format précis de réponse seront définis avec la lecture des requêtes. Pour une consultation de liste, un résultat vide ne signifie pas une erreur : la requête a réussi et peut renvoyer une collection vide avec le statut 200 OK.
Considérez ensuite GET /api/commandes/42. Si l’identifiant correspond à une commande connue, l’opération réussit ; si aucune commande ne correspond, le statut est 404 Not Found. Cette distinction sera importante lorsque vous validerez les identifiants et les paramètres de route : un chemin mal formé et une ressource absente ne décrivent pas le même cas.
Documenter les opérations avant de les coder
Avant d’implémenter une opération, vérifiez trois points : la ressource visée, la méthode qui décrit l’action et les statuts possibles en cas de réussite ou d’échec. Par exemple, la suppression d’une commande existante se distingue d’une suppression d’un identifiant absent par le résultat HTTP, même si le chemin demandé suit la même forme. Inscrire ces choix dans la documentation évite que les clients de l’API aient à deviner le comportement.
À retenir
- Les collections commandes et produits sont identifiées par des chemins au pluriel, respectivement /api/commandes et /api/produits.
- GET consulte, POST crée dans une collection, PATCH modifie partiellement un élément et DELETE demande sa suppression.
- Un identifiant ajouté au chemin désigne un élément précis ; une ressource absente conduit généralement à 404 Not Found.
- Utilisez 200 pour une opération réussie avec résultat, 201 pour une création, 204 pour une réussite sans contenu, 400 pour une requête invalide et 500 pour une erreur inattendue.
Dans la prochaine leçon, vous ajouterez la lecture des requêtes et le format JSON normalisé qui rendra ce contrat concret dans les réponses de l’API.