4.1Construire une API REST complète (CRUD + structure MVC)
Vous savez router avec Express (3-1) et persister des données (3-3, 3-4). Il est temps d'assembler tout cela en une API REST complète et bien structurée — l'un des livrables les plus courants d'un développeur Node. REST (REpresentational State Transfer) est un STYLE d'architecture pour concevoir des API web, largement adopté. Ses principes clés : on expose des ressources (les entités de votre application : utilisateurs, produits, articles…) identifiées par des URL claires (/users, /products), et on agit dessus avec les méthodes HTTP selon leur sémantique : GET /users (lister), GET /users/:id (lire un), POST /users (créer), PUT/PATCH /users/:id (modifier), DELETE /users/:id (supprimer). L'API renvoie des données en JSON avec les bons codes de statut (200 OK, 201 Created, 400 Bad Request, 404 Not Found…). C'est un ensemble de conventions cohérentes qui rendent l'API prévisible et facile à consommer — pour un front-end (React, Vue…), une application mobile, ou un autre service.
Construire une API qui grossit sans devenir un plat de spaghetti exige une structure. Le pattern classique est le MVC (Model-View-Controller) ou ses variantes, qui SÉPARE les responsabilités : les modèles (Model) — la structure et l'accès aux données (vos schémas Mongoose/Prisma) ; les contrôleurs (Controller) — la logique de traitement de chaque requête (recevoir la requête, appeler les modèles, renvoyer la réponse) ; les routes — la définition des URL et méthodes, qui délèguent aux contrôleurs (dans une API JSON, il n'y a pas de « View » HTML — la « vue » est la réponse JSON, ou bien un front séparé). Une structure typique de projet : un dossier routes/ (les définitions d'URL), controllers/ (la logique), models/ (les données), plus souvent middlewares/, services/ (logique métier réutilisable), config/, utils/. Cette organisation rend le code compréhensible (on sait où trouver quoi), maintenable (on modifie une couche sans casser les autres), testable et évolutif. On utilise aussi le Router d'Express (express.Router()) pour regrouper les routes par ressource dans des fichiers séparés (un routeur users, un routeur products…) et les monter sur l'app. Les bonnes pratiques d'une API REST bien conçue : des URL cohérentes et au pluriel (/users), les bonnes méthodes HTTP pour les bonnes actions, les bons codes de statut, une gestion d'erreurs propre (section 4-4), la pagination des listes, le versionnage (/api/v1/...), et une réponse JSON structurée. Une API REST bien construite (ressources, méthodes HTTP sémantiques, codes de statut justes, structure MVC) est prévisible, professionnelle et agréable à consommer — c'est un livrable central du développement back-end, et savoir en concevoir une proprement (pas juste « ça marche » mais bien structurée et conforme aux conventions REST) est une compétence très recherchée. C'est ici que convergent tous les acquis précédents (HTTP, Express, bases de données, modules) en un tout cohérent : une vraie application serveur.
Vocabulaire de la section
- API REST
- Style d'architecture d'API web : exposer des ressources (URL claires) manipulées par les méthodes HTTP selon leur sémantique, réponses en JSON avec les bons codes de statut.
- Ressources & méthodes HTTP
- GET /users (lister), GET /users/:id (lire un), POST /users (créer), PUT/PATCH /users/:id (modifier), DELETE /users/:id (supprimer) — conventions cohérentes.
- MVC / séparation des responsabilités
- Modèles (données), Contrôleurs (logique de traitement), Routes (URL déléguant aux contrôleurs) ; sépare les préoccupations pour un code maintenable et évolutif.
- express.Router()
- Outil regroupant les routes par ressource dans des fichiers séparés (routeur users, products…) montés sur l'app ; organise une API qui grossit.
- Bonnes pratiques REST
- URL cohérentes au pluriel, bonnes méthodes/codes de statut, gestion d'erreurs propre, pagination, versionnage (/api/v1/), réponse JSON structurée.
Qu'est-ce qui distingue une API REST « bien conçue » d'une qui « marche » ?
En pratique — Construire une API REST structurée
- Concevez les endpoints d'une ressource selon REST : GET /items (lister), GET /items/:id (lire), POST /items (créer), PUT /items/:id (modifier), DELETE /items/:id (supprimer).
- Structurez le projet en couches : routes/ (URL), controllers/ (logique), models/ (données) — séparez les responsabilités (MVC).
- Utilisez `express.Router()` pour regrouper les routes d'une ressource dans un fichier, monté sur l'app (`app.use('/api/items', itemsRouter)`).
- Renvoyez du JSON avec les bons codes de statut (201 après création, 404 si non trouvé, 400 si données invalides) et pensez pagination/versionnage.
Points clés à retenir
- API REST : exposer des RESSOURCES (URL claires au pluriel : /users) manipulées par les MÉTHODES HTTP selon leur sémantique (GET/POST/PUT/DELETE), en JSON avec les bons CODES DE STATUT.
- CRUD REST : GET /users (lister), GET /users/:id (lire), POST /users (créer, 201), PUT/PATCH /users/:id (modifier), DELETE /users/:id (supprimer).
- STRUCTURER en couches (MVC) : models (données), controllers (logique), routes (URL) + services/middlewares. Code compréhensible, maintenable, testable, évolutif.
- `express.Router()` regroupe les routes par ressource. Bonnes pratiques : URL cohérentes, bons codes, gestion d'erreurs, pagination, versionnage (/api/v1/). Une API bien conçue est prévisible et professionnelle.
Questions fréquentes
Qu'est-ce qui distingue une API REST « bien conçue » d'une API qui « marche » simplement ?
C'est une distinction essentielle qui sépare le code amateur du code professionnel : une API peut « fonctionner » (renvoyer les bonnes données) tout en étant mal conçue (incohérente, imprévisible, difficile à consommer et à maintenir). Une API BIEN conçue respecte des conventions et une structure qui la rendent prévisible, professionnelle et agréable. Voici ce qui fait la différence. (1) Des URL cohérentes et sémantiques. Mal conçu : des URL incohérentes et verbales (/getUsers, /user_create, /deleteUserById). Bien conçu : des URL basées sur les RESSOURCES, au pluriel, cohérentes (/users pour la collection, /users/:id pour un élément), où l'ACTION est portée par la MÉTHODE HTTP, pas par l'URL. On ne met pas de verbe dans l'URL (pas /getUsers mais GET /users). Cette cohérence rend l'API prévisible : connaissant la convention, on DEVINE les endpoints. (2) Les bonnes MÉTHODES HTTP. Mal conçu : tout en GET ou tout en POST (utiliser POST pour lire, GET pour supprimer…). Bien conçu : chaque méthode selon sa SÉMANTIQUE — GET pour lire (sans effet de bord), POST pour créer, PUT/PATCH pour modifier, DELETE pour supprimer. Respecter la sémantique HTTP est fondamental (et a des implications : GET peut être mis en cache, ne doit pas modifier de données ; etc.). (3) Les bons CODES DE STATUT. Mal conçu : renvoyer 200 pour tout, même les erreurs (une API qui renvoie 200 avec un message d'erreur dans le corps). Bien conçu : les codes de statut appropriés — 200 (succès), 201 (créé, après POST), 204 (succès sans contenu), 400 (requête invalide), 401 (non authentifié), 403 (non autorisé), 404 (non trouvé), 409 (conflit), 500 (erreur serveur). Les codes communiquent CLAIREMENT le résultat au client, qui peut réagir en conséquence. Une API qui renvoie 200 pour une erreur trompe ses consommateurs. (4) Une STRUCTURE de code claire (MVC/couches). Mal conçu : toute la logique entassée dans les fichiers de routes, un plat de spaghetti où données, logique et routage se mélangent. Bien conçu : séparation en couches (routes → contrôleurs → modèles/services), chaque responsabilité isolée. Maintenable, testable, évolutif. (5) Une gestion d'ERREURS propre. Mal conçu : erreurs non gérées (le serveur plante ou renvoie des messages cryptiques), pas de format d'erreur cohérent. Bien conçu : gestion centralisée des erreurs (middleware, section 4-4), réponses d'erreur structurées et cohérentes (un format JSON d'erreur uniforme avec un message clair et le bon code de statut), pas de fuite de détails techniques sensibles. (6) La VALIDATION des entrées. Mal conçu : accepter n'importe quelle donnée (risque de données corrompues, de failles). Bien conçu : valider les entrées (section 4-4) et renvoyer des 400 clairs si invalides. (7) Des réponses JSON STRUCTURÉES et cohérentes. Bien conçu : un format de réponse cohérent (structure des objets, conventions de nommage, gestion des listes avec pagination). (8) La PAGINATION des listes : ne pas renvoyer 10 000 éléments d'un coup, mais paginer (?page=2&limit=20) — performance et scalabilité. (9) Le VERSIONNAGE : préfixer (/api/v1/...) pour pouvoir faire évoluer l'API sans casser les clients existants. (10) La DOCUMENTATION : une bonne API est documentée (les endpoints, les paramètres, les réponses) — pour ceux qui la consomment. (11) La SÉCURITÉ : authentification/autorisation appropriées (section 4-2), protection contre les failles. Pourquoi ces différences comptent : (1) une API bien conçue est PRÉVISIBLE (les consommateurs devinent son fonctionnement grâce aux conventions) — cruciale car une API est faite pour être CONSOMMÉE (par un front, une app mobile, d'autres services, parfois des tiers) ; (2) elle est MAINTENABLE (structure claire) et ÉVOLUTIVE (versionnage) ; (3) elle est PROFESSIONNELLE (respecte les standards du métier) ; (4) elle FACILITE le travail de tous ceux qui l'utilisent. Une API qui « marche » mais est mal conçue fonctionne en démo, mais devient un cauchemar en production et en équipe (incohérences, bugs, difficultés de maintenance et d'intégration). Le message : viser non pas « ça marche » mais « c'est bien conçu » — respecter les conventions REST (ressources, méthodes, codes de statut), structurer le code (couches), gérer les erreurs et la validation, penser pagination/versionnage/sécurité/documentation. Cette rigueur distingue le développeur professionnel. Concevoir de BONNES API (pas juste des API fonctionnelles) est une compétence très recherchée, car les API sont au cœur des architectures modernes (elles connectent front et back, services entre eux, applications et mobiles). Investissez dans cette qualité de conception dès vos premières API — c'est ce qui fait la différence sur le marché du travail et dans les projets réels.
Faut-il vraiment structurer en MVC/couches dès le début, même pour une petite API ?
La réponse nuancée : adaptez le niveau de structure à la TAILLE et à l'ambition du projet, mais adoptez de BONNES habitudes de séparation tôt, car les projets grandissent presque toujours plus que prévu. Voyons comment doser. Pour une TRÈS PETITE API (quelques endpoints, un projet d'apprentissage, un prototype jetable) : une structure ultra-formelle (des dossiers séparés pour tout) peut être excessive au tout début. Vous pouvez commencer plus simplement. MAIS même là, adoptez les principes de base : ne mélangez pas TOUT dans un seul fichier géant, séparez au minimum la logique de la définition des routes. Pour une API RÉELLE (destinée à grandir, à être maintenue, en équipe) : OUI, structurez en couches dès le début, car : (1) Les projets grandissent. Un projet qui commence « petit » grossit presque toujours — de nouveaux endpoints, de nouvelles fonctionnalités s'ajoutent. Si vous avez tout entassé dans des fichiers de routes sans structure, vous vous retrouvez vite avec un plat de spaghetti ingérable, et refactoriser après coup est douloureux. Structurer tôt (quand c'est facile) évite cette dette. (2) La séparation des responsabilités facilite tout. Séparer routes (URL) / contrôleurs (logique) / modèles (données) rend le code compréhensible (on sait où trouver et modifier quoi), maintenable (on change une couche sans casser les autres), testable (on teste les couches isolément — section 4-4), et permet la collaboration (plusieurs personnes sur des parties différentes). Ces bénéfices valent dès qu'un projet dépasse le trivial. (3) C'est une bonne HABITUDE. Prendre l'habitude de structurer proprement dès le début fait de vous un meilleur développeur ; bricoler sans structure « parce que c'est petit » installe de mauvaises habitudes. Comment DOSER (le pragmatisme) : (1) Petit projet / apprentissage : commencez avec une séparation légère — au minimum, séparez les routes de la logique (ne mettez pas 200 lignes de logique dans une définition de route). Utilisez express.Router() pour organiser les routes par ressource. C'est déjà une bonne base sans lourdeur excessive. (2) Projet réel / qui va grandir : structurez en couches complètes (routes/, controllers/, models/, services/, middlewares/, config/, utils/). L'investissement initial est vite rentabilisé. (3) Évoluez : vous pouvez commencer simple et RESTRUCTURER quand le projet grossit — mais anticipez (il est plus facile de partir sur une bonne structure que de refactoriser un gros désordre). Le principe directeur : la structure doit servir la CLARTÉ et la MAINTENABILITÉ, pas être un dogme. Pour un script de 20 lignes, une architecture en 8 couches serait absurde (sur-ingénierie). Pour une API destinée à grandir, une bonne structure est un investissement essentiel. Le bon sens : plus le projet est gros/durable/collaboratif, plus la structure formelle se justifie ; plus il est petit/jetable/solo, plus on peut simplifier — mais TOUJOURS avec une séparation minimale (ne pas tout mélanger). Une recommandation pratique pour l'apprentissage : (1) apprenez la structure MVC/couches (comprenez le POURQUOI : séparer données, logique, routage) — c'est une compétence importante ; (2) appliquez-la sur des projets un peu sérieux (pas juste « ça marche » mais bien organisé) — c'est formateur et ça installe les bonnes habitudes ; (3) pour de tout petits essais, une version allégée suffit, mais gardez la séparation de base (routes vs logique). Ne tombez PAS dans le piège inverse (sur-structurer un minuscule projet avec des couches inutiles) ni dans le piège du désordre (tout mélanger « parce que c'est petit »). En résumé : structurez proportionnellement à l'ambition du projet, mais adoptez les principes de séparation tôt (ne mélangez jamais tout), car les projets grandissent et la structure paie sur la durée. Pour une API réelle, la structure en couches (MVC) dès le début est un investissement rentable. Pour l'apprentissage, pratiquez cette structure sur des projets sérieux pour ancrer les bonnes habitudes. La capacité à bien STRUCTURER un projet est une marque de maturité de développeur — cultivez-la, en l'adaptant intelligemment au contexte.