Changer de passerelle API est rarement un projet que l'on choisit par plaisir. Les déclencheurs que nous rencontrons sont plus prosaïques : fin de support d'une version, renouvellement de licence, exigence de réversibilité, consolidation après une fusion, ou volonté de reprendre la main sur un composant devenu critique. Que l'on parte d'un produit d'éditeur ou d'un service managé, la contrainte est la même : les consommateurs ne doivent rien remarquer.

Cet article décrit la méthode que nous appliquons. Elle ne dépend ni de la passerelle de départ ni de celle d'arrivée.

Le vrai périmètre : les contrats, pas la configuration

L'erreur classique est de traiter la migration comme une conversion de configuration : on exporte les APIs de l'ancienne passerelle, on les traduit, on les importe dans la nouvelle. Or ce que les consommateurs utilisent n'est pas la configuration, c'est un contrat, au sens large :

  • l'URL, les chemins, les méthodes et les formats de requête et de réponse ;
  • le mode d'authentification et la forme des jetons ou des clés ;
  • les codes d'erreur et le format des messages d'erreur ;
  • les en-têtes ajoutés ou supprimés par la passerelle ;
  • les limites de trafic et le comportement en cas de dépassement ;
  • les délais d'expiration, la taille maximale des messages, le traitement des caractères spéciaux.

Une partie de ce contrat n'est écrite nulle part : elle résulte du comportement par défaut de l'ancienne passerelle. C'est précisément cette partie implicite qui casse lors des migrations.

Étape 1 : inventorier ce qui est réellement utilisé

Avant de migrer quoi que ce soit, il faut savoir :

  • quelles APIs sont appelées, par qui, et à quelle fréquence ;
  • quelles versions sont encore utilisées ;
  • quels modes d'authentification sont en service ;
  • quelles APIs ne sont plus appelées du tout.

Les journaux et statistiques de la passerelle actuelle sont la source principale. Cet inventaire a presque toujours un effet de bord utile : une partie du catalogue peut être retirée au lieu d'être migrée. La part concernée se détermine au cas par cas, à partir de l'usage réel.

Étape 2 : écrire le contrat implicite

Pour chaque API migrée, on capture le comportement observable de l'ancienne passerelle : réponses nominales, réponses d'erreur, en-têtes, comportement sous limite de trafic. La forme la plus utile est une suite de tests de contrat exécutable contre n'importe quelle passerelle :

  • elle est d'abord jouée contre l'ancienne passerelle, pour vérifier qu'elle décrit bien la réalité ;
  • elle est ensuite jouée contre la nouvelle, et chaque écart est soit corrigé, soit accepté explicitement et communiqué aux consommateurs.

C'est le cœur de la méthode : la migration est terminée quand la suite passe sur la nouvelle passerelle, pas quand la configuration est importée.

Étape 3 : séparer l'intention du format

Plutôt que de traduire directement le format A en format B, nous décrivons chaque API dans un format neutre (contrat OpenAPI ou WSDL, description lisible des politiques, valeurs par environnement), versionné dans Git. La couche de déploiement traduit ensuite vers la passerelle cible.

Ce détour coûte un peu au début, mais il rapporte deux fois : la migration devient reproductible, et la prochaine migration, car il y en aura une, part d'une base indépendante du produit.

Étape 4 : faire coexister les deux passerelles

Une bascule « big bang » un week-end est la méthode la plus risquée. Nous préférons faire coexister les deux passerelles derrière un point d'entrée commun (répartiteur de charge, DNS ou routage en amont) :

  1. la nouvelle passerelle est déployée, l'API y est configurée, la suite de contrat passe ;
  2. une petite part du trafic, ou un consommateur pilote volontaire, est dirigée vers la nouvelle passerelle ;
  3. on observe : taux d'erreur, latence, écarts de comportement ;
  4. on augmente progressivement, API par API ou consommateur par consommateur ;
  5. l'ancienne passerelle reste prête à reprendre le trafic tant que la bascule n'est pas confirmée.

Cette coexistence demande d'anticiper deux points délicats : les identités (clés ou clients OAuth doivent être reconnus par les deux passerelles pendant la transition) et les quotas (un consommateur réparti sur deux passerelles ne doit pas voir sa limite doublée ou divisée sans qu'on l'ait décidé).

Étape 5 : prévoir le retour arrière, et le tester

Chaque étape de bascule doit pouvoir être annulée rapidement, par le même mécanisme que celui qui l'a déclenchée : changement de routage, pas réinstallation. Un retour arrière qui n'a jamais été joué n'existe pas. Nous le testons volontairement en recette, puis au moins une fois sur un périmètre réel à faible enjeu.

Étape 6 : communiquer avec les consommateurs

Même une migration réussie peut surprendre un consommateur qui dépendait d'un comportement non documenté. Ce qui aide :

  • prévenir les consommateurs avant chaque vague, avec un interlocuteur identifié ;
  • publier les écarts acceptés (par exemple un format d'erreur légèrement différent) avant qu'ils ne soient découverts en production ;
  • proposer un environnement où les consommateurs peuvent tester contre la nouvelle passerelle.

Les pièges fréquents

  • Migrer les APIs mortes. L'inventaire évite de transporter de la dette.
  • Oublier les comportements par défaut. Délais, tailles maximales, encodages : ils font partie du contrat.
  • Changer de passerelle et de contrat en même temps. On migre d'abord à contrat constant, on fait évoluer ensuite. Mélanger les deux rend tout écart impossible à attribuer.
  • Sous-estimer les identités. La migration des clés, des clients OAuth et des certificats est souvent le chemin critique.
  • Décommissionner trop tôt. L'ancienne passerelle reste disponible, au moins en lecture, jusqu'à la confirmation complète.

Ce qu'il faut retenir

Une migration de passerelle réussie se mesure à ce que les consommateurs ne voient pas. Pour y arriver : inventorier ce qui est réellement utilisé, écrire le contrat implicite sous forme de tests, séparer l'intention du format, faire coexister les passerelles, et ne jamais basculer sans retour arrière testé. Le choix de la passerelle d'arrivée compte, mais moins que la méthode.

À côté du conseil, CAB Ingénierie édite STOA, iPaaS souverain, plateforme d'API et d'intégration.

Parlons de votre projet

Vous préparez un changement de passerelle, ou vous voulez évaluer ce qu'il coûterait ? Décrivez-nous votre contexte en quelques lignes : cab-ingenierie.com · contact@cab-ingenierie.com