Créer une API REST avec un framework moderne : le guide qui change tout

On m'a posé la question trois fois cette semaine, dans trois contextes différents : « comment tu fais une API REST propre, aujourd'hui ? ». À chaque fois, j'ai donné la même réponse, et à chaque fois elle a déçu. Parce que la vraie réponse n'est pas un framework. C'est une méthode. Et la méthode, on ne la trouve presque jamais dans les résultats qui remontent quand on tape « créer une API REST ».

Je vais vous la donner ici, avec les noms, le code, et les erreurs que j'ai commises en la construisant. Spoiler : j'ai perdu plus de temps sur la validation des données que sur l'architecture elle-même.

Créer une API REST avec un framework moderne : choisir sans se tromper

Première chose à comprendre : « moderne » ne veut pas dire « récent ». Ça veut dire que le framework fait trois choses sans que vous ayez à les bricoler — la sérialisation, la validation des entrées, et la génération du contrat d'API. Tout le reste est cosmétique.

Le comparatif concret

J'ai utilisé les quatre dans des projets en production. Voici ce que j'en retire, sans filtre marketing.

Framework	Langage	Points forts	Ce qui coince
FastAPI	Python	Async natif, OpenAPI auto-généré, Pydantic intégré	Écosystème plus jeune sur certaines briques d'observabilité
NestJS	TypeScript / Node	Structure modulaire forte, décorateurs, injection de dépendances	Verbeux au démarrage, courbe d'apprentissage réelle
Spring Boot	Java	Maturité, tooling, communauté immense	Démarrage lent, configuration XML pour certains modules historiques
Django REST Framework	Python	ORM puissant, admin intégré, sérialiseurs éprouvés	Moins performant en async pur, dépendance forte à Django

Mon choix par défaut, quand je démarre un projet neuf et que je n'ai pas de contrainte d'équipe : FastAPI. Pas parce qu'il serait « meilleur » dans l'absolu — c'est un débat sans fin — mais parce qu'il m'a fait gagner environ deux jours par projet rien que sur la génération de la documentation. Sur un projet de trois mois, ça compte.

Attention à un piège que j'ai vu plusieurs fois : choisir NestJS parce qu'un article le disait « plus scalable ». La scalabilité d'une API dépend de votre base de données et de votre cache, pas de votre framework de routage. J'ai vu une API FastAPI tenir 4 000 requêtes par seconde sur un petit VPS, et une API Node mal conçue s'écrouler à 200.

Structure d'un projet qui ne pourrit pas en six mois

Le dossier dans lequel j'ai le plus souvent vu des projets partir en vrille : la structure elle-même. Pas le code. La structure.

Une erreur que j'ai faite au tout début, sur un projet de gestion de factures : j'ai tout mis dans un seul fichier main.py. Trois cents lignes. Puis six cents. Puis j'ai dû ajouter une deuxième personne sur le projet, et là, on a passé une semaine à découper ce qui aurait dû l'être dès le premier jour.

La découpe qui fonctionne

Voici celle que j'applique systématiquement maintenant :

• routers/ — un fichier par ressource métier (users, orders, invoices…)
• schemas/ — les modèles Pydantic ou Zod, séparés des modèles de base de données
• services/ — la logique métier, jamais dans les handlers
• repositories/ — l'accès aux données, isolé derrière une interface
• core/ — configuration, sécurité, dépendances partagées
• tests/ — miroir de l'arborescence

Le point qui revient le plus souvent en revue de code : la logique métier dans le handler. Un handler, c'est trois lignes. Il reçoit, il délègue, il renvoie. Si votre handler fait plus de quinze lignes, il y a un problème de découpe quelque part.

Franchement, cette séparation m'a sauvé plus d'une fois quand il a fallu changer de base de données en cours de route. Les repositories absorbent le changement, les services ne bougent pas, les routes non plus.

Un exemple concret : la ressource « commandes »

Prenons un cas réel, celui d'une petite API de commandes pour une boutique. Cinq endpoints, pas plus.

Le code

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

class OrderIn(BaseModel):
    customer_id: int
    items: list[int]

class OrderOut(BaseModel):
    id: int
    customer_id: int
    status: str

app = FastAPI()

@app.post("/orders", response_model=OrderOut, status_code=201)
async def create_order(payload: OrderIn):
validation déjà faite par Pydantic
    order = await order_service.create(payload)
    return order

Regardez ce qui n'est pas dans ce code : pas de vérification de type manuelle, pas de parsing de JSON, pas de gestion d'erreur 422 écrite à la main. FastAPI et Pydantic s'en occupent. C'est exactement ce que j'appelle « moderne ».

Sur ce projet, j'ai réduit le nombre de bugs en production de environ 60 % par rapport à une version précédente écrite avec un micro-framework sans validation. Les erreurs les plus fréquentes — mauvais type de champ, champ manquant, valeur hors bornes — disparaissent avant même d'atteindre le handler.

Les routes REST, sans se prendre la tête

La convention REST est stable depuis longtemps, et elle est simple :

1. GET /orders — liste
2. GET /orders/{id} — détail
3. POST /orders — création
4. PATCH /orders/{id} — mise à jour partielle
5. DELETE /orders/{id} — suppression

Notez l'usage de PATCH et non PUT pour les mises à jour. J'ai longtemps utilisé PUT par habitude, jusqu'à ce qu'un collègue me fasse remarquer qu'à chaque mise à jour partielle, j'obligeais le client à renvoyer l'objet entier. Sur une ressource avec quinze champs, c'est absurde.

Sécurité et authentification : ce qui compte vraiment

Le sujet sur lequel je vois le plus de bricolage. Trois mécanismes, trois usages :

• Clé API — pour un service à service, un script interne, une intégration simple. Rapide à mettre en place, à révoquer facilement.
• JWT — pour une API consommée par une application front, avec des utilisateurs identifiés. Attention à l'expiration et à la rotation des clés de signature.
• OAuth2 — dès que vous devez déléguer l'autorisation à un tiers (connexion via un fournisseur externe, par exemple).

Le point qui manque presque partout : le rate limiting. J'ai eu une API mise à genoux par un client qui bouclait sans backoff sur un endpoint de recherche. Une limite simple — 60 requêtes par minute par clé — aurait suffi. Depuis, je l'ajoute dès le premier jour, même sur un projet interne.

Et Swagger, dans tout ça ?

Swagger, c'est l'ancien nom d'OpenAPI. Aujourd'hui, on parle d'OpenAPI, et la bonne nouvelle c'est que les frameworks modernes le génèrent pour vous. FastAPI expose /docs et /redoc sans que vous écriviez une ligne de configuration. NestJS a un module dédié. Spring Boot a springdoc-openapi.

Ce que je fais systématiquement maintenant : je consulte /docs avant d'écrire le premier test d'intégration. Si la documentation générée ne correspond pas à ce que j'attendais, c'est que mon schéma est mal défini. Ça m'a évité des dizaines d'allers-retours.

Déploiement et tests : les deux choses qui font la différence

Un fichier docker-compose.yml correct vaut mieux qu'un pipeline CI/CD de trois cents lignes que personne ne comprend. J'ai appris ça à la dure, sur un projet où le pipeline avait été écrit par quelqu'un qui avait quitté l'équipe.

Le minimum viable : l'API, la base de données, un reverse proxy (nginx ou Caddy). Trois services, un fichier, deux commandes pour démarrer. Le reste peut attendre.

Côté tests, une règle que j'applique : un test d'intégration par endpoint critique, pas plus. Les tests unitaires sur les services, oui, mais ce sont les tests d'intégration qui attrapent les vrais bugs — mauvais code HTTP, format de réponse incorrect, authentification mal branchée.

Dernière chose, et c'est peut-être la plus importante : ne testez pas votre API avec curl uniquement. Utilisez un client HTTP scriptable. J'ai perdu des heures à reproduire à la main des scénarios que trois lignes de script auraient joués en boucle.

Au fond, créer une API REST avec un framework moderne n'est pas un problème de technologie. C'est un problème de discipline : séparer ce qui doit l'être, valider avant de traiter, documenter avant d'implémenter, tester avant de déployer. Le framework n'est qu'un outil pour tenir cette discipline. Et si vous devez n'en retenir qu'une seule chose, prenez celle-ci : le jour où votre API aura deux ans, ce ne sont pas vos choix de framework qui vous sauveront la mise, mais la clarté de vos frontières internes.