Changelog d'API : quoi publier et qui le lit

Un changelog d’API est le registre daté de chaque changement qu’un appelant pourrait remarquer, écrit pour ceux qui intègrent l’API plutôt que pour l’équipe qui la livre. Ce public en fait un document différent d’un changelog produit : le lecteur décide si son code fonctionnera encore le mois prochain. La plupart échouent de la même façon, en étant une copie filtrée d’un flux interne de releases, si bien qu’un champ supprimé se retrouve à côté d’une correction de texte avec le même poids, et aucun des deux n’est lu.

Qu’est-ce qu’un changelog d’API ?

C’est le registre public et daté des changements apportés à une interface contre laquelle d’autres ont écrit du code. Le test utile pour savoir si quelque chose y a sa place n’a rien à voir avec l’ampleur du changement en interne. Il demande si un appelant correct, écrit l’an dernier et jamais retouché depuis, pourrait se comporter différemment à cause de lui. Ce test admet certains changements très petits et exclut certains très gros.

Tout ce qui suit suppose que l’appelant est extérieur à l’entreprise et effectivement injoignable autrement que via ce document. Quand l’appelant est une autre équipe de la même entreprise, le calcul change assez pour mériter son propre traitement ; changelogs d’API interne couvre ce dont ce public a besoin à la place.

Comment écrire un guide de migration d’API couvre ce dernier document en entier ; en bref, c’est ce vers quoi une entrée de changement incompatible devrait renvoyer plutôt que d’essayer de le remplacer.

Les cinq sont des documents séparés avec des cycles de vie séparés. Un avis de dépréciation est une promesse avec une date, et il appartient aussi au changelog, mais une entrée de changelog s’écrit une fois tandis qu’une dépréciation se suit jusqu’à son sunset. Les confondre est la raison pour laquelle les sunsets sont manqués.

Que doit contenir une entrée ?

Six choses, et les trois premières sont celles qui manquent le plus souvent. Le changement, formulé en termes de requête ou de réponse plutôt que du composant interne. S’il casse un appelant correct. Ce que l’appelant doit faire, y compris “rien”. La date de prise d’effet. La ou les versions concernées. Un lien vers le guide de migration s’il en existe un.

Une entrée qui dit “amélioration de l’endpoint comptes” échoue sur les six. Une entrée qui dit “le champ accounts.type retourne désormais individual là où il retournait personal ; les valeurs existantes restent inchangées pour les comptes créés avant le 2 septembre ; aucune action requise sauf si vous comparez la chaîne” répond aux six en une phrase.

Classez les entrées par conséquence, pas par équipe. Trois étiquettes portent presque toute la valeur : breaking, additive et fixed. Semantic Versioning définit déjà précisément les deux premières, et emprunter ses définitions plutôt qu’en inventer d’autres signifie qu’un lecteur qui connaît semver connaît vos étiquettes. Keep a Changelog en propose un jeu plus large si vous le voulez, et sa règle centrale s’applique ici plus fortement que partout ailleurs : le journal est écrit pour des humains, et un déversement de titres de commit n’en est pas un.

En quoi un changelog d’API diffère-t-il des notes de version ?

Les notes de version décrivent ce que le produit peut faire désormais. Un changelog d’API décrit quel est désormais le contrat. Le même travail livré produit souvent une entrée dans les deux, rédigée différemment, car les publics ont besoin de choses différentes : un nouveau format d’export est une fonctionnalité pour un utilisateur et une nouvelle valeur d’enum pour un appelant qui teste ce champ.

La conséquence pratique est que les deux ne peuvent pas être le même flux avec un style différent. Un appelant abonné à tout ce que vous livrez finira par se désabonner, et ratera alors le changement cassant. Si vous publiez un flux, filtrez-le ; si vous en publiez deux, resserrez celui de l’API et ne laissez jamais une entrée marketing y entrer. Nous comparons les deux formes côte à côte dans changelog vs notes de version.

Où un changelog d’API devrait-il vivre ?

À côté de la documentation de référence, sur une URL stable, avec chaque entrée adressable individuellement via un fragment ou son propre chemin. Les appelants lient des entrées dans des revues d’incidents et des tickets internes, et une entrée qui ne peut pas être liée finit collée en capture d’écran à la place.

Publiez-le aussi en sortie lisible par machine, en plus d’une page. Un flux JSON suivant la spécification JSON Feed ou un flux RSS ne coûte rien une fois les entrées structurées en données, et c’est ce qui permet à un client d’intégrer vos changements dans son propre processus de release. C’est aussi ce qui décide si quelqu’un construit dessus. GitHub documente ses versions de la REST API juste à côté de la référence, pour la même raison : la politique de versionnage fait partie de l’interface.

À quoi ressemble une bonne entrée en pratique ?

Trois entrées de la même semaine, sous la forme décrite ci-dessus :

2026-09-02  Breaking  v2
  `POST /invoices` rejette désormais une `currency` qui ne correspond
  pas à la devise du compte du client, en retournant 422 au lieu de
  convertir silencieusement. Les appelants qui comptaient sur la
  conversion doivent envoyer la devise du compte. Concerne uniquement
  v2 ; v1 reste inchangée jusqu'à son sunset le 2027-01-15.

2026-09-02  Additive  v1, v2
  `Invoice` gagne un horodatage `settled_at`, null jusqu'au règlement
  de la facture. Aucune action requise. Les clients qui rejettent les
  champs inconnus devraient être mis à jour.

2026-08-31  Fixed  v2
  `GET /invoices?status=` retournait une page vide au lieu d'un 400
  pour un statut inconnu. Retourne désormais 400 avec les valeurs
  acceptées. Les appelants ayant fait une faute de frappe voyaient
  auparavant zéro résultat et voient désormais une erreur.

La troisième est le type le plus souvent omis, car en interne c’est une correction de bug. Pour un appelant qui a construit un retry autour de cette page vide, c’est un changement de comportement, et l’entrée est ce qui évite le ticket de support. L’étiquette dit fixed et le corps dit ce qu’un appelant pourrait remarquer, ce qui est la distinction qui garde le journal honnête sans gonfler chaque correction en changement cassant.

Comment les appelants s’y abonnent-ils ?

Donnez-leur plus d’un canal, car ils ont des tâches différentes. Un flux pour le développeur qui veut tout. Un email pour celui qui ne veut que les changements cassants. Des en-têtes de réponse pour le code lui-même, le seul abonné qui n’oublie jamais de vérifier : l’en-tête Sunset défini dans la RFC 8594 place la date de retrait dans la réponse, où une bibliothèque cliente peut la journaliser.

Le canal que la plupart des équipes sautent est le direct. Si un appelant a utilisé le champ que vous changez la semaine dernière, vous savez qui il est, et un email à ces comptes vaut plus que n’importe quelle diffusion générale. C’est la même discipline que fermer la boucle de feedback client, appliquée à un changement que personne n’a demandé : les personnes concernées sont averties individuellement, et tous les autres reçoivent le flux. Un webhook est un quatrième canal avec son propre mode d’échec à connaître avant de s’y fier : les changelogs de webhooks couvre pourquoi un changement de payload là-bas casse en silence, sans appelant pour rejeter la nouvelle forme.

Comment rédiger une entrée pour un changement cassant ?

Commencez par la rupture, pas par la raison. Un appelant qui parcourt dix entrées doit savoir dès la première phrase si celle-ci va lui coûter du travail. Puis la date, les versions concernées, la migration, et l’échéance si l’ancien comportement disparaît plutôt que de changer.

Mettez le même contenu dans l’avis de dépréciation, l’en-tête de réponse et l’email direct, formulé de façon cohérente, et donnez aux quatre la même date. Un écart entre eux est l’erreur qui transforme un changement planifié en incident, car l’appelant qui n’a lu que l’un d’eux agit sur la mauvaise date. Qu’est-ce qu’un changement cassant couvre la décision elle-même, et comment déprécier une API couvre le calendrier qui suit.

Chez changeloop, un changement d’API devient une entrée quand la pull request est fusionnée, une personne édite et approuve le brouillon, et l’entrée est publiée sur le flux et le widget au moment même où un appelant dont le retour via le widget est devenu l’issue GitHub que la pull request ferme en est averti sur cette issue. L’étape de relecture est celle qui compte ici : un changelog d’API est un document contractuel, et aucun brouillon ne devrait atteindre un appelant sans qu’une personne l’ait lu.

FAQ

Chaque changement d’API a-t-il besoin d’une entrée de changelog ? Tout changement qu’un appelant correct pourrait remarquer, oui, y compris ceux que vous jugez internes. Les changements sans effet observable sur la requête ou la réponse non, et les ajouter entraîne les lecteurs à survoler.

Le changelog d’API devrait-il vivre dans la doc ou sur le site marketing ? Dans la doc, juste à côté de la référence. Le lecteur y est déjà la plupart du temps, et un changelog sur le site marketing tend à gagner un public pour lequel il n’a pas été écrit.

Jusqu’où devrait-il remonter ? Indéfiniment. Les entrées sont citées des années plus tard dans des revues d’incidents, et un journal tronqué casse ces liens. Paginez plutôt que d’élaguer.

Faut-il un changelog séparé par version d’API ? Non, un seul journal avec un champ version par entrée est plus facile à lire et à chercher. Filtrer par version est une fonctionnalité de la page, pas une raison de scinder le document.

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