Comment écrire un guide de migration d'API

Un guide de migration d’API est le document qui transforme un changement incompatible en checklist plutôt qu’en panne : ce qui a changé, quoi faire, et avant quand. Une entrée de changelog peut nommer un changement incompatible en deux phrases ; un guide de migration est ce qu’une appelante ouvre vraiment quand ces deux phrases disent « ça te casse » et qu’elle a besoin de savoir exactement quoi modifier. Publier l’entrée sans le guide, c’est comment une appelante apprend un changement incompatible par un ticket de support plutôt que par le document écrit pour l’éviter.

Qu’est-ce qu’un guide de migration d’API ?

Un document étape par étape qui fait passer une appelante de l’ancienne forme d’une API à la nouvelle, écrit pour quelqu’un qui a du code à changer, pas pour quelqu’un qui décide encore d’adopter l’API. Cette distinction compte : un guide de migration suppose une intégration existante et du trafic de production existant, donc il doit couvrir le rollback, la migration partielle, et comment savoir si la migration a réussi, rien de tout cela n’étant nécessaire à un guide de première intégration.

Un guide de migration se situe généralement entre les deux derniers : un avis de dépréciation lance un compte à rebours, et le guide de migration est ce qu’une appelante suit avant que ce compte n’expire.

Quand un changement a-t-il besoin d’un guide de migration, pas seulement d’une entrée de changelog ?

Quand il y a plus d’une étape entre l’ancien comportement et le nouveau, ou quand le changement touche assez de points d’appel pour qu’une appelante bénéficie d’un exemple travaillé plutôt que d’une description. Qu’est-ce qu’un changement incompatible, et comment le livrer couvre le test pour savoir si un changement est incompatible ; une fois la réponse oui, la seconde question est de savoir si la correction est une modification d’une ligne ou une vraie migration. Un champ renommé, une appelante peut le gérer avec la seule entrée de changelog. Un changement à l’authentification, à la pagination ou à la gestion des erreurs mérite presque toujours un guide, parce que le code de remplacement correct n’est pas évident à partir d’une description d’une phrase.

Que doit contenir un guide de migration ?

Cinq choses, et en sauter une seule est ce qui transforme un guide en une page qu’une appelante lit une fois puis abandonne pour procéder par essais-erreurs. L’ancien code, montré tel qu’il apparaîtrait vraiment dans un projet. Le nouveau code, montré de la même façon, pas comme une description abstraite de la différence. Ce qui casse si rien ne change, dit clairement, parce que « rien » est une réponse valide et courante qu’une appelante a quand même besoin d’entendre explicitement. Un moyen de vérifier que la migration a fonctionné, comme un champ de réponse ou un code de statut à vérifier. Et un calendrier : quand l’ancien comportement arrête de fonctionner, et si les deux formes sont disponibles entre-temps.

## Migration des champs monétaires de float vers entier (v3.0.0)

Avant :
  { "amount": 19.99 }

Après :
  { "amount": 1999 }  // plus petite unité monétaire (centimes)

Ce qui change : `amount` est maintenant un entier dans la plus petite
unité de la devise du compte. Le code qui lit `amount` comme un float
lira une valeur 100 fois trop grande à partir du 1er octobre 2026.

Vérifier : après migration, un débit de 19,99 € devrait se lire
`amount: 1999`, pas `amount: 19.99`.

Calendrier : v2 continue de renvoyer des floats jusqu'au 15 janvier
2027. v3 renvoie des entiers dès le lancement. Les deux versions sont
actives maintenant.

Chacune de ces cinq choses répond à une question qu’une appelante devrait sinon deviner ou poser au support, et c’est exactement le coût qu’un guide de migration économise.

Qui devrait l’écrire, et quand ?

Qui a conçu le changement, au moment même où il est livré, pas une équipe support qui le reconstitue plus tard à partir de tickets. Qui a pris la décision sait sur quelles parties de l’ancien comportement personne n’aurait dû compter et lesquelles étaient un contrat accidentel ; un guide écrit plus tard par quelqu’un sans ce contexte a tendance soit à trop expliquer l’évident, soit à manquer le seul cas limite qui casse vraiment les gens. Le guide et l’entrée de changelog qui annonce le changement incompatible devraient sortir ensemble, l’entrée renvoyant vers le guide plutôt que de le répéter.

Comment cela se rattache-t-il au versionnage et au changelog d’API ?

Directement : un guide de migration est la version détaillée de ce qu’une entrée MAJOR dans semantic versioning et votre changelog ne résume qu’en une phrase. L’entrée de changelog dit qu’un changement est incompatible et grosso modo ce qui a changé ; le guide de migration est le lien que cette entrée devrait porter. Changelog d’API : quoi publier et qui le lit liste le guide de migration comme l’un des cinq documents qu’une API maintient, chacun répondant à une question différente ; celui-ci répond à « comment je passe vraiment de A à B », et il mérite sa propre page précisément parce que cette réponse est généralement trop longue pour une entrée de changelog.

Combien de temps un guide de migration devrait-il rester publié ?

Au moins aussi longtemps que l’ancien comportement reste accessible, et idéalement après aussi. Une appelante qui migre dix-huit mois trop tard, après avoir ignoré trois avis de dépréciation, a quand même besoin du guide, et le supprimer le jour où l’ancien comportement est coupé garantit seulement que l’appelante qui en a le plus besoin ne le trouve pas. Gardez-le à une URL stable et mettez à jour la section calendrier plutôt que de retirer la page. Le guide de mise à niveau de Stripe est un exemple public de ce schéma : une seule page, tenue à jour release après release, plutôt qu’un nouveau document par version qui devient obsolète dès que la suivante sort. Votre propre guide mérite un endroit tout aussi facile à trouver, à côté de la documentation qu’une appelante lit déjà, plutôt qu’enterré dans des archives de blog.

FAQ

Chaque changement incompatible a-t-il besoin d’un guide de migration ? Non. Un changement qu’une appelante peut corriger avec la seule entrée de changelog, comme un champ renommé avec un remplacement évident, n’a pas besoin d’un guide séparé. Un changement qui touche plusieurs points d’appel ou nécessite un exemple travaillé, oui.

Un guide de migration devrait-il vivre avec la documentation de l’API ou dans le changelog ? Avec la documentation, lié depuis l’entrée de changelog. L’entrée est ce qu’une abonnée voit en premier ; le guide est ce dont elle a besoin une fois qu’elle a décidé d’agir, et il appartient juste à côté du matériel de référence qu’une appelante utilise déjà.

Quelle est la différence entre un guide de migration et un avis de dépréciation ? Un avis de dépréciation indique que quelque chose va disparaître et avant quand. Un guide de migration, ce sont les instructions pour agir en conséquence. Un avis de dépréciation sans guide de migration lié donne à une appelante une échéance sans lui dire comment la respecter.

Faut-il documenter à la fois l’ancien et le nouveau comportement pendant une fenêtre de migration ? Oui, sur la même page si possible, pour qu’une appelante voie exactement ce qui a changé plutôt que de le reconstituer à partir de deux documents séparés écrits à des moments différents.

Les affirmations techniques de cet article n'ont pas été vérifiées de façon indépendante. Si quelque chose est faux, dis-le-nous et nous le corrigerons.

À voir sur changeloop : Documentation développeurs, Exemples de changelog