Créer une API REST avec Node.js et Express

Les API REST constituent l'épine dorsale de la plupart des applications web et mobiles modernes. Elles permettent à différents systèmes de communiquer entre eux de manière standardisée et efficace. Node.js, combiné au framework Express, offre une solution rapide et élégante pour construire des API robustes. Chez MapWay, c'est notre stack de prédilection pour les backends de nos applications cartographiques comme TMaps et Houni.tn.

Les principes fondamentaux d'une API REST

REST (Representational State Transfer) est un style d'architecture défini par Roy Fielding en 2000. Une API REST bien conçue repose sur plusieurs principes clés qui garantissent sa maintenabilité et sa scalabilité.

Ressources identifiées par des URI : chaque entité (utilisateur, produit, localisation) est accessible via une URL unique et prévisible, comme /api/v1/locations ou /api/v1/users/:id.
Méthodes HTTP standardisées : GET pour lire, POST pour créer, PUT/PATCH pour modifier, DELETE pour supprimer. Chaque méthode a une sémantique précise.
Sans état (Stateless) : chaque requête contient toutes les informations nécessaires à son traitement. Le serveur ne conserve aucun contexte de session entre les requêtes.
Réponses au format JSON : le JSON est devenu le format standard pour les échanges de données, remplaçant le XML par sa simplicité et sa légèreté.

Structurer un projet Express professionnel

Un projet Express bien structuré est essentiel pour la maintenabilité à long terme. Voici l'architecture que nous recommandons chez MapWay, éprouvée sur des dizaines de projets en production :

L'architecture en couches sépare les responsabilités de manière claire. Le dossier routes contient les définitions des endpoints et la validation des entrées. Le dossier controllers gère la logique de traitement des requêtes HTTP. Le dossier services contient la logique métier pure, indépendante du protocole HTTP. Et le dossier models définit les schémas de données et les interactions avec la base de données.

Cette séparation permet de tester chaque couche indépendamment, de remplacer une base de données sans toucher à la logique métier, et de réutiliser les services dans d'autres contextes (CLI, workers, scripts de migration).

Middleware : la puissance d'Express

Les middleware sont le concept central d'Express. Ce sont des fonctions qui s'exécutent séquentiellement lors du traitement d'une requête, permettant d'ajouter des fonctionnalités de manière modulaire. Voici les middleware essentiels pour une API en production :

Authentification et autorisation

L'authentification par JWT (JSON Web Tokens) est la méthode la plus répandue pour sécuriser une API REST. Le client reçoit un token signé après connexion et le transmet dans l'en-tête Authorization de chaque requête. Le middleware vérifie la validité du token et extrait les informations de l'utilisateur. Pour les API cartographiques comme celles de MapWay, nous ajoutons souvent une couche d'autorisation basée sur les rôles pour contrôler l'accès aux données géographiques sensibles.

Validation des données

Ne faites jamais confiance aux données entrantes. Des bibliothèques comme Joi ou Zod permettent de définir des schémas de validation stricts et de rejeter automatiquement les requêtes malformées avec des messages d'erreur explicites. Pour les API géographiques, la validation des coordonnées (latitude entre -90 et 90, longitude entre -180 et 180) est particulièrement critique.

Gestion des erreurs

Un middleware de gestion d'erreurs centralisé est indispensable. Il capture toutes les exceptions non gérées, les journalise pour le debugging, et renvoie une réponse JSON structurée au client avec le code HTTP approprié. Distinguez les erreurs opérationnelles (données invalides, ressource non trouvée) des erreurs de programmation (bug, crash) pour les traiter différemment.

Pagination, filtrage et tri

Toute API sérieuse doit implémenter la pagination pour éviter de retourner des milliers d'enregistrements en une seule réponse. Nous recommandons la pagination par curseur pour les jeux de données volumineux (plus performante que la pagination par offset) et la pagination par offset pour les cas simples.

Le filtrage via les query parameters (GET /api/locations?city=tunis&type=restaurant) et le tri (GET /api/locations?sort=-createdAt) doivent être implémentés de manière générique pour éviter la duplication de code entre les différentes ressources.

Sécuriser votre API

La sécurité ne doit jamais être une réflexion secondaire. Voici les mesures essentielles :

Rate limiting : limitez le nombre de requêtes par IP pour prévenir les attaques par déni de service. Le package express-rate-limit est simple à intégrer.
Helmet : ce middleware ajoute automatiquement les en-têtes HTTP de sécurité (CSP, HSTS, X-Frame-Options).
CORS : configurez précisément les origines autorisées à accéder à votre API. Évitez le wildcard (*) en production.
Sanitisation des entrées : protégez-vous contre les injections NoSQL et XSS en nettoyant toutes les données utilisateur.

Documentation avec Swagger/OpenAPI

Une API sans documentation est une API inutilisable. Le standard OpenAPI 3.0, couplé à l'interface Swagger UI, permet de documenter automatiquement vos endpoints et de fournir un espace de test interactif. Chez MapWay, nous générons notre documentation à partir des schémas de validation, garantissant que la documentation est toujours synchronisée avec le code. C'est particulièrement important pour nos API cartographiques utilisées par des partenaires externes.

Performance et mise en cache

Pour les API à fort trafic, la mise en cache est essentielle. Redis est la solution de prédilection pour le cache côté serveur. Pour les données géographiques servies par nos API chez MapWay, nous utilisons un cache à plusieurs niveaux : cache HTTP (ETag, Cache-Control), cache applicatif (Redis) et cache de requêtes de base de données.

La compression gzip des réponses JSON, l'utilisation de la pagination et la sélection de champs (GET /api/locations?fields=name,lat,lng) réduisent significativement la bande passante et améliorent les temps de réponse.

Notre stack API chez MapWay

Nos API en production chez MapWay utilisent Node.js avec Express, connectées à PostgreSQL via PostGIS pour les données spatiales. Nous ajoutons Redis pour le cache, Bull pour les tâches asynchrones, et nous déployons le tout dans des conteneurs Docker. Cette architecture alimente TMaps.tn, Houni.tn et Code-Postale.tn avec une disponibilité de 99.9%.

Que vous construisiez une API simple ou une plateforme complexe, Node.js et Express restent un choix excellent en 2025. La clé réside dans une architecture propre, des bonnes pratiques de sécurité et une documentation rigoureuse.