Routes API Next.js (Route Handlers) : GET, POST, authentification | We.Inc
Des exemples de Route Handlers Next.js à copier pour l'App Router : GET avec paramètres de requête, POST avec validation, params dynamiques sous forme de promesse, contrôles d'authentification, CORS et webhooks.
Dans l'App Router, un endpoint d'API est un fichier route.ts placé dans app, par exemple app/api/todos/route.ts. Exportez des fonctions async nommées d'après les méthodes HTTP, comme GET et POST ; chacune reçoit une Request et renvoie une Response, généralement Response.json(). Les segments dynamiques arrivent sous forme de promesse params que vous attendez avec await. Depuis Next.js 15, les handlers GET sont dynamiques par défaut.
Les bases des Route Handlers
Tâche
Code
Renvoyer du JSON
return Response.json(data, { status: 200 })
Lire un corps JSON
const body = await request.json()
Lire des données de formulaire
const form = await request.formData()
Lire ?q=
request.nextUrl.searchParams.get("q")
Segment dynamique
const { id } = await params
Cookies / en-têtes
await cookies(), await headers() from next/headers
Les routes API du Pages Router utilisaient des objets req et res. Les Route Handlers utilisent à la place les objets Web standard Request et Response, ce qui piège quiconque copie d'anciennes réponses. Voici les modèles dont vous aurez besoin pour une vraie application, chacun écrit pour l'App Router actuel, plus un petit testeur qui montre les codes de statut qu'un POST avec validation doit renvoyer.
Remplissez le corps de requête fictif dans le testeur et indiquez si l'appelant est connecté.
Le testeur applique, dans votre navigateur, les mêmes règles de validation que l'exemple POST de cette page.
Lisez le code de statut et le JSON renvoyés, puis modifiez un champ pour obtenir un 400, un 401 ou un 201.
Copiez le handler d'exemple et remplacez la liste en mémoire par votre base de données.
Traitez chaque handler comme un endpoint public. Vérifiez la session dans le handler, même si le proxy redirige déjà les utilisateurs déconnectés.
Validez le corps avec une bibliothèque de schémas comme Zod et renvoyez un 400 avec les erreurs par champ, plutôt que de laisser une charge utile invalide provoquer un 500.
Un fichier route.ts ne peut pas se trouver dans le même dossier qu'un page.tsx ; placez les API sous app/api pour les séparer.
Si vous n'exportez pas OPTIONS, Next.js y répond pour vous avec un en-tête Allow listant les méthodes que vous avez exportées.
Pour les webhooks, lisez le corps brut avec request.text() avant de l'analyser, car la vérification de signature a besoin des octets exacts.
Questions fréquentes
Les routes API de Next.js sont-elles obsolètes ?
Les routes pages/api fonctionnent toujours dans le Pages Router. Dans l'App Router, l'équivalent est un Route Handler, un fichier route.ts qui utilise les objets Web Request et Response et ne nécessite aucune configuration bodyParser.
Quelles méthodes HTTP un route.ts peut-il exporter ?
GET, POST, PUT, PATCH, DELETE, HEAD et OPTIONS. Appeler une méthode que vous n'avez pas exportée renvoie 405 Method Not Allowed.
Pourquoi faut-il attendre params avec await ?
Depuis Next.js 15, params dans l'argument de contexte est une promesse. Écrivez const { id } = await params. Le type utilitaire RouteContext, généré par next dev, next build ou next typegen, vous donne des params typés d'après le chemin de la route.
Les Route Handlers GET sont-ils mis en cache ?
Plus par défaut. Next.js 15 a fait passer les handlers GET de statiques à dynamiques. Réactivez la mise en cache avec export const dynamic = 'force-static' ou une valeur revalidate. Avec Cache Components activé, placez use cache dans une fonction utilitaire appelée par le handler, pas dans le corps du handler.
Faut-il utiliser un Route Handler ou une Server Action ?
Utilisez une Server Action pour les mutations déclenchées par vos propres formulaires et boutons. Utilisez un Route Handler quand quelque chose d'extérieur à votre arbre React appelle l'URL : une application mobile, un webhook, une tâche cron ou un script tiers.
Organisation des fichiers
Le chemin du dossier est l'URL. app/api/todos/route.ts répond à /api/todos, et app/api/todos/[id]/route.ts répond à /api/todos/42. Un dossier attrape-tout comme [...slug] transmet un tableau de segments.
Les Route Handlers partagent la configuration de segment avec les pages, donc les mêmes exports dynamic, revalidate et runtime s'y appliquent.
Des codes de statut que les clients comprennent
Renvoyez 201 après une création, 400 quand l'entrée est incorrecte, 401 quand personne n'est connecté, 403 quand l'utilisateur connecté n'a pas la permission, 404 quand l'enregistrement n'existe pas et 405 pour les méthodes non prises en charge. Le front-end peut alors réagir selon le code au lieu d'analyser le texte d'erreur.
Renvoyez une forme JSON cohérente pour les erreurs, comme { error: string, fields?: object }, afin qu'une seule fonction fetch puisse toutes les gérer.
Checklist de sécurité
Vérifiez la session, contrôlez que l'utilisateur possède l'enregistrement qu'il modifie, validez la charge utile, et ne renvoyez jamais de secrets ni de lignes utilisateur complètes. Le guide officiel sur l'authentification montre ce modèle en deux temps : un 401 sans session et un 403 pour un mauvais rôle.
Ne définissez les en-têtes CORS que sur les handlers que d'autres origines doivent réellement appeler, et listez les origines précises plutôt qu'un astérisque dès que des cookies sont en jeu.
Exemples de Route Handlers
GET avec une requête de recherche
app/api/todos/route.ts. Le paramètre q filtre la liste ; une requête vide renvoie tout.
POST avec validation Zod et contrôle d'authentification
Renvoie 401 sans session, 400 avec les erreurs par champ pour un corps invalide, et 201 avec le nouvel enregistrement sinon. getSession remplace votre bibliothèque d'authentification.
Segment dynamique avec params attendus
app/api/todos/[id]/route.ts. params est une promesse à partir de Next.js 15.
CORS pour une seule origine de confiance
Répond à la requête préliminaire du navigateur et à la vraie requête avec la même origine autorisée.
Appeler le handler depuis un Client Component
La fonction fetch lit d'abord le code de statut, pour que le formulaire puisse afficher les erreurs par champ d'un 400.
Routes API du Pages Router et Route Handlers
Même tâche, API différentes
pages/api/x.ts
app/api/x/route.ts
Handler
export default function handler(req, res)
export async function GET(request)
Envoyer du JSON
res.status(200).json(data)
return Response.json(data)
Choix de la méthode
if (req.method === "POST")
une fonction POST exportée séparément
Analyse du corps
req.body (configuration bodyParser)
await request.json() ou request.formData()
Chaîne de requête
request.nextUrl.searchParams
Testeur POST
Modifiez un corps JSON, indiquez si l'appelant est connecté, et voyez le code de statut et la réponse que renverrait l'exemple POST avec validation.
Méthode
Corps de la requête (JSON)
L'appelant a une session valide
Réponse
PUT montre le 405 que Next.js renvoie pour une méthode que le fichier n'exporte pas.