Créer une API REST avec un framework backend moderne : le guide

On m'a posé la question trois fois cette semaine, toujours dans les mêmes termes : « et si je veux juste une API propre, je pars sur quoi ? ». À chaque fois, ma réponse change un peu, parce que la vraie question n'est jamais le framework. Elle est : qui va maintenir cette API dans dix-huit mois, et avec quelle énergie ?

Une API REST, c'est un contrat. Des ressources exposées à des URL stables, des verbes HTTP qui portent le sens de l'action, des réponses dans un format que n'importe quel client peut lire. Le reste — le framework, l'ORM, le système de migrations — c'est de la plomberie. Utile, mais secondaire.

Ce qui a changé ces dernières années, ce n'est pas REST. C'est le coût de mise en route d'une API sérieuse. Il a chuté. Et ce changement déplace complètement le critère de choix.

Comment choisir un framework backend moderne pour créer une API REST

Il y a un piège dans lequel je suis tombé deux fois. La première, avec un projet Node.js où j'avais empilé Express, un ORM maison et trois librairies de validation. Résultat : six mois plus tard, plus personne ne comprenait le flux d'une requête sans ouvrir quatre fichiers. La seconde, à l'inverse, avec un framework trop opinionné dont j'ai passé des semaines à contourner les conventions.

Le bon framework est celui dont les défauts par défaut ressemblent à vos besoins.

Les quatre familles qui comptent vraiment

On peut grossièrement ranger les frameworks backend modernes en quatre familles, chacune avec une philosophie distincte.

• Minimalistes (Express, Fiber, Flask) — vous assemblez tout vous-même. Contrôle total, dette technique garantie si vous ne posez pas de règles.
• Structurés avec typage fort (NestJS, FastAPI, Spring Boot) — beaucoup de conventions, un typage qui attrape les erreurs avant l'exécution.
• Batteries-included (Django REST Framework, Laravel) — l'admin, l'auth, les migrations sont fournis. Excellent pour livrer vite un produit métier.
• Asynchrones natifs (FastAPI, Actix, frameworks Go) — pensés pour la concurrence réseau, utiles dès qu'il y a beaucoup d'appels I/O.

Franchement, pour 80 % des projets que je croise, la question se réduit à : est-ce que je veux écrire de l'infrastructure ou est-ce que je veux livrer des fonctionnalités ?

Un comparatif honnête, pas un classement

Framework	Langage	Courbe d'apprentissage	Ce qu'il apporte d'emblée
FastAPI	Python	Douce si vous connaissez Python	Validation via Pydantic, documentation OpenAPI générée
NestJS	TypeScript	Raide au début, très rentable ensuite	Injection de dépendances, modules, décorateurs
Django REST Framework	Python	Modérée, beaucoup de magie	ORM, admin, auth, sérialiseurs
Laravel	PHP	Douce	Eloquent, migrations, sanctum pour l'auth
Spring Boot	Java	Longue	Tout, mais avec un vocabulaire à apprendre

Mon avis tranché : si votre équipe vient du scripting et veut une API documentée en deux jours, FastAPI reste le meilleur rapport effort/résultat. Si vous construisez un produit avec plusieurs développeurs sur la durée, NestJS ou DRF vous feront gagner des mois de discussions sur « où mettre quoi ».

Comment concevoir un endpoint REST qui ne finira pas en dette technique

Une erreur que j'ai commise tôt : dessiner les routes avant de dessiner les données. Ça semble anodin. Ça ne l'est pas.

Partir du modèle de données, pas des routes

Une URL REST bien faite est une projection de votre modèle. Si vous avez des commandes, une commande, et des lignes de commande, vos routes sont déjà écrites dans votre schéma. Le travail de conception consiste à décider ce qui est une collection et ce qui est une ressource unique, pas à inventer des noms.

Concrètement, un endpoint qui mélange deux ressources dans un même objet de réponse est une bombe à retardement. J'ai vu une API de facturation où /invoices/42 renvoyait aussi le profil du client, son adresse, et l'historique de ses paiements. Personne ne pouvait modifier le profil du client sans passer par la facture. Cauchemar.

La règle des verbes HTTP, et pourquoi elle est plus stricte qu'on ne le croit

GET ne modifie rien. PUT remplace. PATCH modifie partiellement. DELETE supprime. POST crée ou déclenche une action.

Ce n'est pas esthétique. C'est un contrat qui détermine si les proxies peuvent mettre en cache, si les clients peuvent réessayer une requête sans risque, si un load balancer peut router correctement. Un GET qui modifie une donnée casse silencieusement tous les mécanismes qui vous protègent en production.

Le test simple : si vous ne pouvez pas rejouer la même requête dix fois sans que l'état change, ce n'est pas un GET ou un PUT. C'est un POST.

Un exemple concret : la même API dans deux frameworks

Voici un endpoint qui crée un utilisateur. Deux approches, deux philosophies.

Avec FastAPI, la validation est déclarative. Le framework génère la documentation OpenAPI et la vérification des entrées à partir du modèle :

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, EmailStr

app = FastAPI()

class UserIn(BaseModel):
    email: EmailStr
    name: str

@app.post("/users", status_code=201)
async def create_user(payload: UserIn):
    existing = await db.users.find_one({"email": payload.email})
    if existing:
        raise HTTPException(status_code=409, detail="Email déjà utilisé")
    user = await db.users.insert_one(payload.model_dump())
    return {"id": str(user.inserted_id)}

Avec NestJS, la même chose passe par un contrôleur, un service et un DTO. Plus de fichiers, mais l'injection de dépendances rend le test unitaire trivial :

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Post()
  async create(@Body() dto: CreateUserDto): Promise<User> {
    return this.usersService.create(dto);
  }
}

La différence n'est pas dans le résultat visible. Elle est dans ce qui se passe quand l'équipe grandit. Le contrôleur NestJS vous oblige à séparer la logique métier du transport HTTP. FastAPI vous laisse tout mettre dans la fonction — ce qui va très bien jusqu'au jour où ça ne va plus.

Authentification, validation, documentation : les trois piliers non négociables

Ce sont les trois sujets sur lesquels je vois le plus de rattrapage douloureux. Une API qui les traite après coup accumule des rustines pendant des mois.

Authentification : choisir avant d'écrire la première route

Deux options dominent aujourd'hui : les JWT signés côté serveur, et les sessions serveur classiques. Les JWT sont pratiques pour les clients mobiles et les architectures distribuées, mais ils compliquent la révocation immédiate. Les sessions sont plus simples à invalider, moins pratiques à scaler horizontalement sans store partagé.

Mon conseil : si vous n'avez pas de raison technique forte de choisir JWT, commencez par des sessions. Vous migrerez si nécessaire. J'ai vu trop de projets implémenter une rotation de refresh tokens avant même d'avoir un seul utilisateur réel.

Validation : le point où la sécurité et la propreté se rejoignent

Chaque entrée doit être validée au niveau du schéma, pas dans le corps de la fonction. Une validation noyée dans la logique métier est une validation qu'on oublie de mettre à jour quand le modèle change.

Pydantic côté Python, class-validator côté NestJS, sérialiseurs côté DRF : tous font le même travail. La règle, elle, ne change pas — un champ non validé est un champ qui deviendra un bug en production.

Documentation : vivante ou morte

Une documentation générée automatiquement (OpenAPI, Swagger) reste synchronisée avec le code. Une documentation écrite à la main ne le reste jamais plus de trois semaines.

Si votre framework ne génère pas la doc, changez de framework.

Le sujet dont personne ne parle : versioning et production

Le moment où votre API devient publique, elle devient un contrat que vous ne pouvez plus casser à volonté. Chaque changement de format est un breaking change potentiel pour un client que vous ne contrôlez pas.

Deux stratégies tiennent la route dans le temps :

1. Versionner dans l'URL (/v1/users) — visible, simple, mais pollue les routes.
2. Versionner dans un en-tête (Accept: application/vnd.api.v2+json) — plus propre, mais moins découvrable pour les nouveaux venus.

La première est plus facile à expliquer. La seconde est plus élégante. Pour 90 % des projets, choisissez la première et cessez d'y penser.

Et côté production, trois choses sont non négociables : des logs structurés (JSON, pas de texte libre), un health check sur un endpoint dédié, et un tracing qui relie une requête entrante à ses appels sortants. Sans ça, déboguer une latence devient un exercice d'archéologie.

Les erreurs que je vois systématiquement

Trois erreurs reviennent plus que les autres dans les revues de code que je fais.

La première : retourner des codes HTTP 200 avec un champ error: true dans le corps. Cela casse tous les clients qui se fient au code HTTP pour décider quoi faire. Ne faites jamais ça.

La deuxième : exposer directement les entités de base de données dans les réponses. Le jour où vous ajoutez une colonne sensible, elle fuite immédiatement.

La troisième, la plus pernicieuse : ne pas prévoir la pagination dès le départ. Une collection qui renvoie « tout » fonctionne sur votre machine de dev avec dix lignes. Elle explose en production avec cent mille.

Une mise en route qui tient la distance

Si je devais redémarrer un projet d'API REST demain, voici l'ordre que je suivrais, dans cet ordre précis :

1. Modéliser les données et les relations (une demi-journée).
2. Choisir un framework dont les défauts correspondent à l'équipe.
3. Poser l'authentification et la structure de dossiers avant d'écrire le premier endpoint métier.
4. Écrire un endpoint de bout en bout, avec tests, logs et doc générée.
5. Déployer cet endpoint unique en préproduction. Vraiment.
6. Alors seulement, écrire les autres.

L'étape 5 est celle que tout le monde saute. C'est celle qui vous évite de découvrir, trois mois plus tard, que votre configuration de proxy ne transmet pas les en-têtes d'authentification.

Le framework que vous choisirez dans dix-huit mois est peut-être déjà sorti. Le modèle de données que vous concevez aujourd'hui, lui, vous le porterez pour des années. C'est là que se joue la vraie qualité d'une API — pas dans le nom de la librairie qui traite vos requêtes.