Article · SaaS & dev
Concevoir une API Next.js avec un contrat vérifiable
Route, validation, erreurs et secrets : les décisions qui rendent une petite API Next.js compréhensible à tester.
Commencer par le contrat
Une route utile répond à quatre questions avant le code : quelle méthode accepte-t-elle, quelle entrée minimale reçoit-elle, quelles sorties sont garanties et quelles erreurs l’appelant peut-il traiter ? Écrivez ces réponses dans un exemple court. Cela évite de transformer chaque changement interne en surprise pour le client.
Dans l’App Router, les Route Handlers Next.js sont une frontière serveur. Les secrets et les accès base de données restent de ce côté ; le navigateur ne reçoit que les champs nécessaires à son interface.
Valider à la frontière
La validation doit rejeter les types inattendus, les champs inconnus si le contrat l’exige et les valeurs hors limites. Une validation de formulaire côté navigateur améliore l’expérience, mais elle ne protège pas la route : l’appel HTTP peut être fabriqué directement.
Retournez une erreur exploitable sans révéler la requête SQL, le chemin serveur ou une variable d’environnement. Une réponse 400 décrit l’entrée invalide ; une 401 ou 403 distingue authentification et autorisation ; une 404 ne confirme pas inutilement l’existence d’une ressource sensible.
Séparer lecture et effets
Une route de lecture devrait rester idempotente. Pour une écriture, vérifiez l’autorisation avant l’opération, employez un identifiant d’idempotence si un retry est possible et journalisez un résultat minimal. Le journal doit permettre de comprendre ce qui s’est passé sans recopier un token ou une donnée personnelle.
Ne faites pas confiance à un identifiant fourni par l’URL pour choisir une destination externe. La ressource doit être résolue dans une liste autorisée côté serveur. Cette règle est particulièrement importante dans un site qui présente des offres ou des redirections.
Tester le chemin réel
Testez au minimum une requête valide, chaque classe d’erreur, une entrée trop grande, une ressource inexistante et une tentative sans permission. Ajoutez un test qui vérifie qu’aucun secret n’apparaît dans la réponse. Vitest convient aux unités ; pour une frontière serveur complète, gardez un test d’intégration ou de parcours séparé, comme le recommande le guide de test Next.js.
Vous pouvez comparer cette approche à la checklist de publication Next.js avant d’exposer la route.
Sources et limites
Sources vérifiées le 21 septembre 2026 : Route Handlers Next.js et tests Next.js. Le présent article ne décrit pas une API métier particulière.