Creer une API REST avec Next.js App Router : guide complet en 7 etapes

Vous avez un front-end Next.js et vous voulez ajouter une API REST sans deployer un backend separe ? Depuis l'App Router (Next.js 13+), c'est non seulement possible, mais c'est devenu la methode recommandee. Les Route Handlers remplacent les anciennes API Routes du Pages Router avec une API plus propre, basee sur les standards Web (Request/Response). Dans ce guide, on va construire une API REST complete, etape par etape, avec validation, authentification et gestion d'erreurs.

Etape 1 : Structurer votre projet

Creez un dossier app/api/ a la racine de votre App Router. Chaque endpoint correspond a un fichier route.ts dans un sous-dossier. Par exemple, app/api/users/route.ts gere /api/users. Cette structure est intuitive et suit le pattern file-based routing de Next.js.

Bonne pratique : groupez vos routes par domaine (app/api/users/, app/api/posts/, app/api/auth/) et creez un dossier lib/ pour les utilitaires partages (validation, middleware, helpers).

Etape 2 : Creer les handlers CRUD

Exportez des fonctions nommees GET, POST, PUT, DELETE depuis votre fichier route.ts. Chaque fonction recoit un objet Request (Web Standard) et retourne un objet Response ou NextResponse. L'avantage sur les anciennes API Routes : vous travaillez avec les standards Web, pas des objets proprietaires.

Pour les routes dynamiques avec parametres (ex: /api/users/[id]), creez un dossier [id]/ avec un fichier route.ts. Le parametre est accessible via le deuxieme argument de la fonction handler.

Etape 3 : Valider les donnees avec Zod

Ne faites jamais confiance aux donnees entrantes. Utilisez Zod pour definir des schemas de validation et validez chaque body de requete POST/PUT. Zod s'integre parfaitement avec TypeScript et infere automatiquement les types. Un schema Zod, c'est votre contrat d'API — lisible, testable et type-safe.

Etape 4 : Ajouter du middleware

Next.js supporte un fichier middleware.ts a la racine du projet. Utilisez-le pour le rate limiting, les headers CORS, le logging et la verification de tokens. Le middleware s'execute avant les Route Handlers, ce qui en fait l'endroit ideal pour les controles transversaux.

Etape 5 : Authentification JWT

Pour securiser vos endpoints, implementez une authentification par JWT. Creez un endpoint /api/auth/login qui verifie les credentials et retourne un token. Puis verifiez ce token dans le middleware pour chaque requete protegee. Utilisez jose (plus leger que jsonwebtoken) pour la verification des tokens dans un environnement Edge.

Etape 6 : Gestion d'erreurs structuree

Creez un helper qui standardise les reponses d'erreur avec un format coherent : code HTTP, message lisible et details optionnels. Enveloppez chaque handler dans un try/catch global. En production, loggez les erreurs 500 vers un service externe (Sentry, Datadog) tout en retournant un message generique au client.

Etape 7 : Deployer en production

Si vous deployez sur Vercel, les Route Handlers sont automatiquement optimises. Pour un deploiement self-hosted, utilisez next build puis next start. Configurez les variables d'environnement, les headers de securite et le rate limiting au niveau infrastructure. N'oubliez pas les tests : utilisez Vitest ou Jest avec supertest pour valider chaque endpoint avant le deploiement.