Next.js + Drupal : contrats d'API pour éviter les régressions front

Pourquoi l'absence de contrat coûte cher

Dans une architecture Next.js + Drupal, le frontend consomme des endpoints JSON:API ou REST générés automatiquement par Drupal. Cette facilité a un revers : l'interface entre les deux systèmes n'est jamais formalisée. Drupal expose tout ce qu'il sait ; Next.js consomme ce dont il a besoin — sans que personne n'ait documenté ni testé cette dépendance.

Les conséquences arrivent toujours au mauvais moment :

• Un champ renommé dans un type de contenu Drupal (field_hero_title devient field_titre_principal) casse silencieusement le composant React qui le consommait.
• Une migration de données modifie la cardinalité d'un champ (de string à array de string) : le front plante sur toutes les pages qui utilisaient ce champ.
• Un module contrib met à jour son schéma JSON:API dans une nouvelle version : les includes imbriqués changent de structure sans avertissement.

À chaque régression, le coût est double : le temps de débogage pour identifier l'origine du problème, et le temps de restauration pour revenir à un état stable.

Ce qu'est un contrat d'API — et ce qu'il n'est pas

Un contrat d'API n'est pas une documentation de l'API. La documentation décrit ce qui existe ; le contrat définit ce qui est garanti et ce qui peut changer.

Un contrat précise :

• Les endpoints consommés : quels types de contenu, quels champs, quels filtres, quelles relations incluses.
• Le schéma de la réponse attendue : types de données, champs obligatoires, valeurs admissibles pour les champs enum.
• Le comportement en cas d'erreur : format des réponses d'erreur, cas d'erreur prévus.
• La politique de versionnement : ce qui peut évoluer sans préavis, ce qui déclenche une version majeure et un délai de migration.

Un contrat n'est pas un document figé. C'est un artefact vivant, versionné dans le dépôt, qui évolue quand l'interface évolue — et qui déclenche une conversation entre équipes avant d'évoluer, pas après.

Définir et versionner vos schémas

La première étape est de formaliser les schémas des réponses que Next.js consomme réellement. L'outil le plus adapté dans l'écosystème headless Drupal / Next.js est JSON Schema — un format déclaratif, lisible par les humains, exploitable par les outils de validation.

Pour chaque type de contenu consommé, définissez un fichier de schéma qui décrit la structure attendue de la réponse JSON:API. Ces fichiers de schéma vivent dans le dépôt Next.js, versionnés avec le code front. Chaque schéma porte un numéro de version dans son nom (article-response.v1.schema.json). Quand l'interface change, on crée article-response.v2.schema.json — le v1 reste jusqu'à ce que la migration soit terminée.

Stabiliser les formats d'erreur

Les régressions ne viennent pas seulement des données manquantes — elles viennent aussi des erreurs mal gérées. JSON:API Drupal retourne des erreurs dans un format standard (errors[] avec title, detail, status), mais les modules contrib peuvent déroger à ce format.

La règle de base : définissez un contrat d'erreur autant qu'un contrat de succès. Pour chaque endpoint, documentez le code HTTP retourné pour chaque cas d'erreur prévisible, la structure du corps d'erreur, et le comportement attendu du front. Un module Drupal custom peut centraliser la normalisation des réponses d'erreur pour garantir que tous les endpoints respectent le format contractualisé.

Valider les payloads avant mise en prod

Un contrat sans validation automatisée est une déclaration d'intention, pas une garantie. La validation des payloads doit s'intégrer dans deux moments du cycle de développement.

Côté front, à l'exécution. La librairie ajv permet de valider chaque réponse API contre son schéma JSON Schema avant de la passer aux composants React. Dans un environnement de développement ou de staging, une validation échouée déclenche une erreur explicite avec le champ concerné et la valeur reçue — au lieu d'un crash silencieux dans le rendu.

Dans la CI, avant déploiement. Un test d'intégration exécute une requête réelle contre l'environnement Drupal de staging et valide la réponse contre le schéma contractualisé. Si le schéma ne correspond plus à la réponse Drupal, le pipeline s'arrête et le déploiement est bloqué — avant d'atteindre la production.

Le cycle de vie d'un contrat

Un contrat d'API suit un cycle de vie structuré, aligné sur les pratiques de versionnement sémantique :

Changement rétrocompatible (minor/patch). Un nouveau champ optionnel est ajouté dans la réponse Drupal. Le contrat existant reste valide ; le front peut choisir de consommer ce champ ou de l'ignorer. Le schéma v1 est mis à jour, le numéro de patch est incrémenté.

Changement non rétrocompatible (major). Un champ obligatoire est renommé ou supprimé. Un schéma v2 est créé. Les deux versions coexistent pendant une période de migration définie (typiquement deux semaines). L'équipe Drupal maintient l'endpoint v1 le temps que le front migre vers v2.

Rupture imprévue. Un changement non planifié casse la compatibilité sans passer par le processus de versionnement. C'est le cas que le contrat cherche à prévenir — et que les tests contractuels dans la CI doivent détecter avant la mise en prod.

Une stratégie de tests contractuels entre équipes

Les tests contractuels sont le mécanisme de vérification que chaque équipe peut exécuter indépendamment pour s'assurer que sa partie du contrat est respectée.

Du côté Drupal. Une suite de tests vérifie que chaque endpoint répond conformément au schéma contractualisé. Ces tests s'exécutent dans la CI Drupal : si une modification du modèle de données casse un schéma, le pipeline Drupal s'arrête avant le déploiement. L'équipe Drupal découvre la régression elle-même, sans attendre que le front remonte l'incident.

Du côté Next.js. Les composants sont testés avec des fixtures générées à partir des schémas contractualisés — pas des données inventées à la main. Ces fixtures garantissent que les tests front couvrent exactement la structure que Drupal s'engage à fournir.

Le point de synchronisation. Le dépôt de contrats (les fichiers de schéma) est la référence partagée entre les deux équipes. Toute modification d'un schéma déclenche une revue impliquant les deux équipes avant d'être fusionnée. C'est le seul moment où une conversation entre front et back est obligatoire — et c'est suffisant.

Ce que ça change dans la pratique

Mettre en place des contrats d'API dans un projet Next.js + Drupal ne demande pas de refonte architecturale. Ça demande une discipline de formalisation : écrire les schémas des endpoints déjà consommés, les versionner, les faire valider dans la CI.

La friction initiale est réelle — documenter ce qui existait implicitement prend du temps. Mais le gain est immédiat : chaque équipe peut déployer sa partie de la stack avec la certitude que l'autre partie sera prévenue d'un changement incompatible avant qu'il n'atteigne la production.

Un front Next.js qui ne tombe plus sur un déploiement Drupal, c'est un contrat d'API qui fonctionne.