Changelogs d'API internes : ce qui change

Chaque autre article de ce hub suppose que l’appelant d’une API est extérieur à l’entreprise : l’ingénieure d’une cliente, une partenaire, quelqu’un qui a trouvé la doc tout seul. Beaucoup d’API ont un type d’appelant complètement différent, une équipe dans le bureau d’à côté ou deux étages plus loin, et ça change le calcul de ce qu’un changelog lui doit, parce qu’un message Slack l’atteint et qu’aucun ticket de support n’est généralement jamais ouvert. La plupart des équipes en concluent que les API internes n’ont pas besoin de changelog. Ce dont elles ont vraiment besoin, c’est d’un différent.

Qu’est-ce qui rend le changelog d’une API interne différent de celui d’une API publique ?

Le public est joignable directement, ce qui supprime la raison principale d’exister de la plupart des changelogs d’API publiques : diffuser vers des appelants qu’on ne peut pas contacter individuellement. L’équipe propriétaire d’une API interne sait généralement exactement quelles autres équipes l’appellent, parfois jusqu’au service précis. Ça fait d’un message ciblé, pas d’un flux public, le choix par défaut naturel, et c’est pour ça que les API internes finissent si souvent sans aucun changelog : l’équipe propriétaire prévient les deux ou trois équipes dont elle se souvient, en supposant que ça couvre tout le monde.

Pourquoi « on préviendra juste les équipes qui nous appellent » s’effondre-t-il ?

Parce que l’ensemble des appelants n’est jamais aussi petit ni aussi statique que l’équipe propriétaire s’en souvient. Un service construit pour une consommatrice gagne un second appelant six mois plus tard, via une intégration que personne n’a annoncée, et la liste mentale « qui nous appelle » de l’équipe propriétaire est désormais fausse sans que personne ne le remarque. L’échec est ordinaire et courant, le résultat par défaut de compter sur la mémoire plutôt que sur un registre, pas le signe que quelqu’un a été négligent. Qu’est-ce qu’un breaking change couvre comment décider si un changement d’API compte comme cassant en premier lieu ; le cas interne ajoute une seconde question, plus difficile, par-dessus celle-là, à savoir qui prévenir.

Une API interne a-t-elle même besoin d’une page de changelog façon publique ?

Généralement oui, même si le canal principal est direct. Une page donne au message direct quelque chose vers quoi pointer, si bien que la notification peut rester courte (« breaking change sur /v2/accounts, détails ici ») plutôt que d’essayer de porter l’explication complète dans un message de chat qui va défiler et disparaître. Elle devient aussi ce qu’une nouvelle équipe, ou une qui a raté le message direct, peut consulter quand son intégration casse et qu’elle essaie de comprendre pourquoi. La page n’a pas besoin d’être soignée ni publique ; elle doit être liable et survivre au fil Slack qui l’a annoncée.

Qui maintient réellement la liste des appelants ?

L’équipe propriétaire, et ça doit être traité comme un vrai artefact, pas comme un savoir tribal. La version la moins chère est un fichier dans le dépôt même de l’API, une courte liste de services consommateurs avec une responsable par entrée, mise à jour chaque fois qu’une nouvelle intégration est construite, la même discipline que n’importe quelle déclaration de dépendance. L’alternative, demander autour de soi avant chaque breaking change, fonctionne jusqu’au jour où quelqu’un oublie de demander à la bonne personne, et une API interne qui casse silencieusement pour une équipe est un incident plus petit qu’un incident public, mais ça reste un incident, généralement découvert par l’astreinte de cette équipe plutôt que par la propriétaire de l’API.

# consumers.yml
- service: billing-service
  owner: "#team-billing"
  since: 2026-03-01
- service: reporting-pipeline
  owner: "#team-analytics"
  since: 2026-06-14

Un fichier comme celui-ci transforme « qui devons-nous prévenir » d’une question en une simple consultation. Des outils construits exactement pour ce problème, comme le catalogue de services de Backstage, modélisent les API comme des entités de premier ordre avec des consommateurs déclarés, pour la même raison : une fois qu’une organisation a assez de services internes, la mémoire de personne sur qui appelle quoi ne reste plus exacte toute seule, et quelque chose doit tenir le registre à sa place. La documentation de l’outil que vous faites déjà tourner en interne est généralement le bon endroit à vérifier avant d’en construire un sur mesure.

Qu’est-ce qui appartient à une entrée de changelog interne qu’une publique n’aurait pas besoin d’avoir ?

Plus de précision opérationnelle, parce que la lectrice est une autre ingénieure qui va agir là-dessus au sein de la même infrastructure, pas le lire comme un résumé. Dans quels environnements le changement est en production et quand, parce que les services internes sont souvent promus par étapes qu’un appelant public ne voit jamais. Si le changement nécessite une mise à jour de configuration ou de bibliothèque client côté consommatrice, formulée comme une commande s’il y en a une. Et, parce que les appelants internes peuvent souvent coordonner le correctif directement avec l’équipe propriétaire, un contact nommé plutôt qu’un canal de support : « préviens @maria si ça casse quelque chose » est une ligne parfaitement raisonnable dans une entrée interne et une ligne étrange dans un changelog d’API publique.

Est-ce que ça s’applique de la même façon à un changelog dans un monorepo ?

Ça aiguise le même problème plutôt que de le remplacer. Changelogs de monorepo couvre quand un package a besoin de son propre changelog ; une API interne qui n’est qu’un package parmi d’autres dans un monorepo a quand même besoin que ses consommateurs soient suivis explicitement, parce que partager le dépôt avec ses appelants ne veut pas dire qu’ils remarqueront un changement à moins que quelque chose ne le leur signale. La proximité dans le dépôt n’est pas la même chose que la proximité dans l’attention.

FAQ

Une API purement interne a-t-elle besoin d’un changelog si elle n’a qu’un seul appelant ? À peine, et un message direct à cette seule équipe suffit généralement. Le changelog se justifie dès qu’il y a plus d’un appelant, ou dès que la liste des appelants a déjà surpris l’équipe propriétaire, parce que c’est le signe que la mémoire seule n’est plus fiable.

Les changements d’API internes devraient-ils passer par la même revue que les publics ? La formulation peut être plus légère, puisque la lectrice est une collègue et non une appelante externe, mais la décision de savoir si un changement est cassant mérite le même soin dans les deux cas. Une appelante interne a quand même du code en production qui dépend de l’ancien comportement.

Comment découvrir qui appelle une API interne si ça n’a jamais été suivi ? Les logs du serveur ou les données de trafic d’un service mesh sont la réponse honnête si aucun registre des consommateurs n’a jamais été tenu ; traitez cette découverte comme le moment d’en commencer un, pas comme un nettoyage ponctuel.

Un message Slack suffit-il, ou un changement interne a-t-il quand même besoin d’une entrée de changelog formelle ? Les deux, pour tout ce qui n’est pas purement additif. Le message est ce qui se lit à temps ; l’entrée est ce qu’une équipe enquêtant sur un problème des semaines plus tard, qui n’a jamais vu le message, peut quand même trouver.

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, Comparatif d'outils de changelog