Maintenir la compatibilité de votre frontend avec l'API qu'il interroge

Vous avez une nouvelle version de votre frontend prête. L'équipe a relu les modifications, les tests sont verts, et le bundle attend sur votre CDN d'être déployé. Mais avant d'actionner le levier, une question est souvent négligée : ce frontend fonctionnera-t-il encore avec l'API qui tourne actuellement en production ?

Le frontend et le backend sont rarement déployés en même temps. L'API peut encore servir une ancienne version alors que votre frontend attend un nouvel endpoint. Ou l'équipe API vient de déployer un changement cassant, et votre frontend a été compilé avant ce changement. Dans les deux cas, les utilisateurs se retrouvent avec des pages cassées, des données manquantes, ou des erreurs silencieuses que personne ne remarque jusqu'à ce qu'un utilisateur se plaigne.

Ce n'est pas un problème d'outil. C'est un problème de coordination qui se manifeste dans votre pipeline.

Pourquoi le frontend et l'API se désynchronisent

Le frontend et le backend ont des rythmes de release fondamentalement différents. Un frontend statique hébergé sur un CDN peut être déployé instantanément. Pas de redémarrage de serveur, pas de vidange de connexion, pas de migration. Vous poussez les fichiers, et la prochaine requête utilisateur les récupère.

Les API backend sont différentes. Déployer une nouvelle version d'API implique souvent de redémarrer les serveurs d'application, d'exécuter des migrations de base de données, ou de mettre à jour la configuration de l'infrastructure. Cela prend du temps et comporte ses propres risques.

Quand ces deux rythmes ne sont pas alignés, vous vous retrouvez avec une fenêtre où le frontend attend une chose et l'API en retourne une autre. Le frontend appelle un endpoint qui n'existe plus. Ou l'API commence à retourner un nouveau champ, et l'ancien frontend plante car il ne peut pas parser la réponse.

Le problème s'aggrave quand différentes équipes possèdent le frontend et l'API. L'équipe frontend peut ne même pas savoir que l'API a changé jusqu'à ce que quelqu'un signale un bug.

Le versioning d'API est la réponse classique, mais il a un coût

La solution la plus courante est de versionner votre API. Vous mettez un préfixe de version dans l'URL, comme /api/v1/commandes et /api/v2/commandes. L'ancien frontend continue d'appeler v1 pendant que le nouveau frontend passe à v2. Les deux versions coexistent jusqu'à ce que l'ancien frontend soit complètement retiré.

Cela fonctionne, mais ce n'est pas gratuit. Maintenir plusieurs versions d'API signifie que votre équipe backend porte une dette technique. Chaque nouvelle fonctionnalité doit être implémentée dans les deux versions, ou vous devez planifier un calendrier de dépréciation. Les utilisateurs doivent éventuellement migrer, et cette migration est elle-même un projet.

Le versioning est un filet de sécurité, mais il est lourd. Pour les équipes qui livrent fréquemment, maintenir deux ou trois versions d'API devient un frein à la vélocité.

Les feature flags vous donnent plus de contrôle

Une approche plus flexible consiste à utiliser des feature flags. Vous livrez le nouveau frontend avec les nouveaux appels API déjà dans le bundle, mais ces appels sont protégés par un flag désactivé. Les utilisateurs téléchargent le nouveau frontend, mais ils n'atteignent jamais le nouvel endpoint car la fonctionnalité est inactive.

Quand l'équipe API termine son déploiement, vous activez le flag depuis un tableau de bord. Le frontend commence à appeler le nouvel endpoint sans nécessiter de nouveau téléchargement. Pas de review App Store, pas de purge de cache CDN, pas de réunion de coordination.

Les feature flags sont particulièrement utiles quand le frontend et l'API sont gérés par des équipes différentes. L'équipe frontend peut livrer selon son calendrier, et l'équipe API selon le sien. Le flag devient le point de coordination unique.

Le compromis est que vous livrez du code qui n'est pas encore actif. Ce code est testé et relu, mais il reste inactif dans le navigateur de l'utilisateur. Si la taille de votre bundle est une préoccupation, vous devez faire attention à la quantité de code mort que vous livrez.

Les tests de contrat détectent les problèmes avant la release

Les feature flags et le versioning gèrent le problème de coordination après coup. Mais vous pouvez aussi détecter l'incompatibilité avant que le frontend n'atteigne la production. Le mécanisme est le test de contrat dans votre pipeline CI/CD.

Voici comment ça fonctionne. Pendant la compilation du frontend, votre pipeline exécute une série de tests de contrat. Ces tests vérifient que les réponses API attendues par votre frontend correspondent aux réponses réelles de l'API. Si l'API retourne un champ que le frontend n'attend pas, ou si un champ est manquant, ou si le type de données a changé, le test de contrat échoue et le pipeline s'arrête.

Voici à quoi ressemble un test de contrat minimal en pratique :

// contract-test.js - exécuté en CI avant de déployer le frontend
async function checkUserEndpoint() {
  const response = await fetch('https://api.example.com/v1/users/1');
  const data = await response.json();

  // Vérifie la structure attendue par le frontend
  if (typeof data.id !== 'number') {
    throw new Error('id doit être un nombre');
  }
  if (typeof data.name !== 'string') {
    throw new Error('name doit être une chaîne');
  }
  if (!Array.isArray(data.roles)) {
    throw new Error('roles doit être un tableau');
  }

  console.log('Test de contrat réussi : /users/:id correspond aux attentes du frontend');
}

checkUserEndpoint().catch(err => {
  console.error('Test de contrat échoué :', err.message);
  process.exit(1);
});

Ce test s'exécute contre l'API live en staging ou en production. Si l'API change un type de champ ou supprime un champ obligatoire, le pipeline échoue avant que le frontend n'atteigne les utilisateurs.

Vous exécutez ces tests de contrat contre la version de l'API qui tourne actuellement en staging ou en production, selon votre stratégie. Le test ne vérifie pas la logique métier. Il vérifie uniquement la structure : la réponse contient-elle les champs dont le frontend a besoin, et sont-ils du bon type ?

Les tests de contrat ne remplacent pas les tests d'intégration. Les tests d'intégration vérifient que l'ensemble du système fonctionne correctement. Les tests de contrat vérifient seulement que le frontend et l'API peuvent communiquer sans planter. Mais pour les problèmes de compatibilité, les tests de contrat sont exactement ce dont vous avez besoin. Ils sont rapides, ils s'exécutent dans chaque pipeline, et ils détectent la classe la plus courante de désynchronisations frontend-backend.

Combinez ces approches pour un filet de sécurité pratique

Aucune technique unique ne couvre tous les scénarios. Le versioning d'API gère la coexistence à long terme. Les feature flags gèrent les décalages de timing de release. Les tests de contrat détectent les problèmes avant qu'ils n'atteignent les utilisateurs.

Le diagramme suivant peut vous aider à décider quelle approche correspond à votre situation :

flowchart TD A[Frontend et API désynchronisés ?] --> B{Est-ce un changement cassant majeur ?} B -->|Oui| C[Utilisez le versioning d'API] B -->|Non| D{Le backend n'est-il pas encore prêt ?} D -->|Oui| E[Utilisez les feature flags] D -->|Non| F{Avez-vous besoin de détecter les écarts avant la release ?} F -->|Oui| G[Ajoutez des tests de contrat dans le CI] F -->|Non| H[Aucune action nécessaire] C --> I[Planifiez un calendrier de dépréciation] E --> J[Livrez le code frontend inactif, activez le flag plus tard] G --> K[Le pipeline échoue en cas d'écart de structure] I --> L[Combinez avec les flags et les tests pour un filet complet] J --> L K --> L

Une configuration pratique ressemble à ceci :

  • Utilisez le versioning d'API pour les changements cassants majeurs qui affectent de nombreux consommateurs.
  • Utilisez les feature flags pour la coordination au niveau des fonctionnalités entre les équipes frontend et backend.
  • Ajoutez des tests de contrat à votre pipeline frontend comme une barrière qui empêche le déploiement de builds incompatibles.

Cette combinaison vous offre plusieurs couches de protection sans forcer chaque équipe à suivre le même calendrier de release.

Une checklist rapide pour votre pipeline

Si vous mettez en place des vérifications de compatibilité pour la première fois, voici une courte liste pour démarrer :

  • Identifiez les endpoints API dont dépend votre frontend.
  • Écrivez des tests de contrat qui vérifient la structure de chaque réponse.
  • Exécutez ces tests contre l'API actuelle de staging ou de production dans votre pipeline CI frontend.
  • Configurez le pipeline pour échouer si un test de contrat échoue.
  • Pour les fonctionnalités qui ne sont pas prêtes côté backend, encapsulez les appels frontend dans un feature flag.
  • Planifiez un calendrier de dépréciation pour les anciennes versions d'API et communiquez-le à toutes les équipes frontend.

Ce qui compte le plus

La compatibilité frontend-backend n'est pas une nouveauté technique. C'est une réalité quotidienne pour toute équipe qui livre du code frontend contre une API en production. Le risque n'est pas que votre code ait des bugs. Le risque est que votre code soit correct, mais qu'il dialogue avec la mauvaise version de l'API.

Le versioning, les feature flags et les tests de contrat résolvent chacun une partie différente de ce problème. Utilisez-les ensemble, et votre pipeline deviendra une barrière fiable qui empêche le code incompatible d'atteindre les utilisateurs.