Interne API-changelogs: wat verandert er

Elk ander artikel in dit hub gaat ervan uit dat degene die een API aanroept buiten het bedrijf zit: de engineer van een klant, een partner, iemand die de docs zelf vond. Veel API’s hebben een heel ander soort aanroeper, een team aan de andere kant van de gang of twee verdiepingen verderop, en dat verandert de afweging van wat een changelog hen verschuldigd is, omdat een Slack-bericht hen bereikt en er meestal nooit een supportticket wordt geopend. De meeste teams concluderen hieruit dat interne API’s geen changelog nodig hebben. Wat ze echt nodig hebben, is een andere.

Wat maakt de changelog van een interne API anders dan die van een publieke?

Het publiek is rechtstreeks bereikbaar, wat de belangrijkste reden wegneemt waarom de meeste publieke API-changelogs bestaan: uitzenden naar aanroepers die je niet individueel kunt bereiken. Het team dat een interne API bezit, weet meestal precies welke andere teams hem aanroepen, soms tot op de specifieke service. Dat maakt een gericht bericht, geen publieke feed, de natuurlijke standaard, en daarom eindigen interne API’s zo vaak zonder enige changelog: het eigenaarsteam waarschuwt de twee of drie teams die het zich herinnert, in de veronderstelling dat dat iedereen dekt.

Waarom faalt “we lichten gewoon de teams in die ons aanroepen”?

Omdat de groep aanroepers nooit zo klein of zo statisch is als het eigenaarsteam zich herinnert. Een service gebouwd voor één consument krijgt zes maanden later een tweede aanroeper, via een integratie die niemand aankondigde, en de mentale lijst “wie roept ons aan” van het eigenaarsteam klopt nu niet meer zonder dat iemand het merkt. De fout is gewoon en veelvoorkomend, het standaardresultaat van vertrouwen op geheugen in plaats van op een register, geen teken dat iemand nalatig was. Wat is een breaking change behandelt hoe je beslist of een API-wijziging überhaupt als breaking telt; het interne geval voegt daar een tweede, moeilijkere vraag aan toe, namelijk weten wie je moet inlichten.

Heeft een interne API überhaupt een changelog-pagina in publieke stijl nodig?

Meestal wel, ook al is het primaire kanaal direct. Een pagina geeft het directe bericht iets om naar te linken, zodat de melding kort kan blijven (“breaking change in /v2/accounts, details hier”) in plaats van te proberen de volledige uitleg in een chatbericht te proppen dat wegscrollt. Het wordt ook wat een nieuw team, of een team dat het directe bericht miste, kan checken wanneer hun integratie breekt en ze proberen te achterhalen waarom. De pagina hoeft niet gepolijst of publiek te zijn; hij moet linkbaar zijn en de Slack-thread overleven die hem aankondigde.

Wie onderhoudt eigenlijk de lijst van aanroepers?

Het eigenaarsteam, en dat moet behandeld worden als een echt artefact, niet als stamkennis. De goedkoopste versie is een bestand in de eigen repository van de API, een korte lijst van consumerende services met een eigenaar per item, bijgewerkt telkens wanneer een nieuwe integratie wordt gebouwd, dezelfde discipline als elke afhankelijkheidsverklaring. Het alternatief, rondvragen voor elke breaking change, werkt tot de ene keer dat iemand vergeet de juiste persoon te vragen, en een interne API die stilletjes breekt voor één team is een kleiner incident dan een publiek, maar het blijft een incident, meestal ontdekt door de eigen wachtdienst van dat team in plaats van door de eigenaar van de API.

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

Zo’n bestand maakt van “wie moeten we inlichten” een opzoeking in plaats van een vraag. Tools die precies voor dit probleem zijn gebouwd, zoals Backstage’s service catalog, modelleren API’s als eersteklas entiteiten met vastgelegde consumenten om dezelfde reden: zodra een organisatie genoeg interne services heeft, blijft niemands geheugen van wie wat aanroept vanzelf accuraat, en moet iets anders het register bijhouden. De docs van welke tool je intern ook al draait, zijn meestal de juiste plek om te checken voordat je zelf iets bouwt.

Wat hoort in een interne changelog-entry die een publieke niet nodig zou hebben?

Meer operationele specificiteit, omdat de lezer een andere engineer is die hierop zal handelen binnen dezelfde infrastructuur, en het niet als samenvatting zal lezen. In welke omgevingen de wijziging live is en wanneer, omdat interne services vaak door stadia gepromoveerd worden die een publieke aanroeper nooit ziet. Of de wijziging een configuratie- of client-library-update aan de kant van de consument vereist, geformuleerd als een commando als die er is. En, omdat interne aanroepers de fix vaak rechtstreeks met het eigenaarsteam kunnen afstemmen, een met naam genoemd contact in plaats van een supportkanaal: “stuur @maria een bericht als dit iets breekt” is een volkomen redelijke regel in een interne entry en een vreemde in een publieke API-changelog.

Geldt dit op dezelfde manier voor een changelog binnen een monorepo?

Het verscherpt hetzelfde probleem in plaats van het te vervangen. Monorepo-changelogs behandelt wanneer een package zijn eigen changelog nodig heeft; een interne API die één van meerdere packages in een monorepo is, heeft zijn consumenten alsnog expliciet bijgehouden nodig, omdat dezelfde repository delen met wie hem aanroept niet betekent dat ze een wijziging opmerken tenzij iets hen erop wijst. Nabijheid in de repo is niet hetzelfde als nabijheid in aandacht.

FAQ

Heeft een puur interne API een changelog nodig als hij maar één aanroeper heeft? Nauwelijks, en een direct bericht aan dat ene team volstaat meestal. De changelog verdient zichzelf terug zodra er meer dan één aanroeper is, of zodra de lijst met aanroepers het eigenaarsteam ooit heeft verrast, want dat is het signaal dat geheugen alleen niet meer betrouwbaar is.

Zouden interne API-wijzigingen dezelfde review moeten doorlopen als publieke? De formulering mag lichter zijn, omdat de lezer een collega is en geen externe aanroeper, maar de beslissing of een wijziging breaking is verdient in beide gevallen dezelfde zorg. Een interne aanroeper heeft alsnog productiecode die van het oude gedrag afhangt.

Hoe kom je erachter wie een interne API aanroept als dat nooit is bijgehouden? Serverlogs of de verkeersdata van een service mesh zijn het eerlijke antwoord als er nooit een consumentenregister werd bijgehouden; behandel die ontdekking als het moment om er een te beginnen, niet als een eenmalige opruiming.

Is een Slack-bericht genoeg, of heeft een interne wijziging alsnog een formele changelog-entry nodig? Beide, voor alles dat niet puur additief is. Het bericht is wat op tijd gelezen wordt; de entry is wat een team dat weken later een probleem onderzoekt, en het bericht nooit zag, alsnog kan vinden.

De technische beweringen in dit artikel zijn niet onafhankelijk gecontroleerd. Klopt er iets niet, laat het ons weten, dan corrigeren we het.

Meer op changeloop: Documentatie voor ontwikkelaars, Changelog-tools vergeleken