API-changelog: wat je publiceert, en wie het leest

Een API-changelog is het gedateerde overzicht van elke wijziging die een aanroeper zou kunnen opmerken, geschreven voor wie tegen de API integreert, niet voor het team dat hem uitbrengt. Dat publiek maakt het een ander document dan een productchangelog: de lezer beslist of zijn code volgende maand nog werkt. De meeste falen op dezelfde manier, als gefilterde kopie van een interne release-feed, waardoor een verwijderd veld naast een tekstcorrectie staat met hetzelfde gewicht, en geen van beide wordt gelezen.

Wat is een API-changelog?

Het is het publieke, gedateerde logboek van wijzigingen aan een interface waar anderen code tegen hebben geschreven. De bruikbare test of iets erin thuishoort heeft niets te maken met hoe groot de wijziging intern was. Hij vraagt of een correcte aanroeper, vorig jaar geschreven en sindsdien niet aangeraakt, zich hierdoor anders zou kunnen gedragen. Die test laat sommige heel kleine wijzigingen toe en sluit sommige heel grote uit.

Alles hieronder gaat ervan uit dat de aanroeper buiten het bedrijf zit en effectief niet bereikbaar is behalve via dit document. Wanneer de aanroeper een ander team binnen hetzelfde bedrijf is, verandert de afweging genoeg om een eigen behandeling te verdienen; interne API-changelogs behandelt wat dat publiek in plaats daarvan nodig heeft.

Hoe je een API-migratiegids schrijft behandelt dat laatste document volledig; kort gezegd is het waar een breaking-change-regel naar zou moeten linken in plaats van het te proberen te vervangen.

De vijf zijn aparte documenten met aparte levenscycli. Een deprecation-melding is een belofte met een datum, en hoort ook thuis in de changelog, maar een changelog-item wordt eenmaal geschreven terwijl een deprecation gevolgd wordt tot de sunset. Ze door elkaar halen is waarom sunsets gemist worden.

Wat hoort in één item?

Zes dingen, en de eerste drie zijn wat meestal ontbreekt. De wijziging, geformuleerd in termen van het verzoek of de respons in plaats van het interne component. Of het een correcte aanroeper breekt. Wat de aanroeper moet doen, inclusief “niets”. De datum waarop het van kracht werd. De betrokken versie of versies. Een link naar de migratiegids als die bestaat.

Een item dat zegt “accounts-endpoint verbeterd” faalt op alle zes. Een item dat zegt “het veld accounts.type geeft nu individual terug waar het eerder personal teruggaf; bestaande waarden blijven ongewijzigd voor accounts aangemaakt vóór 2 september; geen actie nodig tenzij je de string vergelijkt” beantwoordt alle zes in één zin.

Categoriseer items op gevolg, niet op afdeling. Drie labels dragen bijna alle waarde: breaking, additive en fixed. Semantic Versioning definieert de eerste twee al precies, en die definities lenen in plaats van eigen definities verzinnen betekent dat een lezer die semver kent jouw labels kent. Keep a Changelog biedt een langere set als je die wilt, en de kernregel geldt hier sterker dan waar dan ook: het logboek is voor mensen, en een dump van commit-titels is dat niet.

Hoe verschilt een API-changelog van release notes?

Release notes beschrijven wat het product nu kan. Een API-changelog beschrijft wat het contract nu is. Hetzelfde uitgebrachte werk produceert vaak een item in beide, anders geformuleerd, omdat de publieken andere dingen nodig hebben: een nieuw exportformaat is een functie voor een gebruiker en een nieuwe enum-waarde voor een aanroeper die op dat veld schakelt.

Het praktische gevolg is dat de twee niet dezelfde feed met andere styling kunnen zijn. Een aanroeper die zich abonneert op alles wat je uitbrengt, meldt zich uiteindelijk af, en mist dan de breaking change. Publiceer je één feed, filter hem dan; publiceer je er twee, maak de API-feed dan smaller en laat er nooit een marketingitem in. We vergelijken beide vormen naast elkaar in changelog vs release notes.

Waar moet een API-changelog leven?

Naast de referentiedocumentatie, op een stabiele URL, met elk item afzonderlijk adresseerbaar via een fragment of een eigen pad. Aanroepers linken naar items in incidentanalyses en interne tickets, en een item dat niet gelinkt kan worden, wordt in plaats daarvan als screenshot geplakt.

Publiceer het ook als machineleesbare output, naast een pagina. Een JSON-feed volgens de JSON Feed-specificatie of een RSS-feed kost niets zodra items gestructureerde data zijn, en het is wat een klant in staat stelt jouw wijzigingen in zijn eigen releaseproces op te nemen. Dit bepaalt ook of iemand erop voortbouwt. GitHub documenteert zijn REST API-versies om dezelfde reden vlak naast de referentie: het versiebeleid maakt deel uit van de interface.

Hoe ziet een goed item er in de praktijk uit?

Drie items uit dezelfde week, in de hierboven beschreven vorm:

2026-09-02  Breaking  v2
  `POST /invoices` weigert nu een `currency` die niet overeenkomt met de
  accountvaluta van de klant, en geeft 422 terug in plaats van stil te
  converteren. Aanroepers die vertrouwden op conversie moeten de
  accountvaluta meesturen. Betreft alleen v2; v1 blijft ongewijzigd tot
  de sunset op 2027-01-15.

2026-09-02  Additive  v1, v2
  `Invoice` krijgt een `settled_at`-tijdstempel, null totdat de factuur
  betaald is. Geen actie nodig. Clients die onbekende velden weigeren,
  moeten worden bijgewerkt.

2026-08-31  Fixed  v2
  `GET /invoices?status=` gaf een lege pagina terug in plaats van een 400
  bij een onbekende status. Geeft nu 400 terug met de geaccepteerde
  waarden. Aanroepers met een typefout zagen eerder nul resultaten,
  zien nu een fout.

De derde is het type dat het vaakst wordt weggelaten, omdat het intern een bugfix is. Voor een aanroeper die een retry rond die lege pagina had gebouwd, is het een gedragswijziging, en het item is wat het supportticket voorkomt. Het label zegt fixed en de body zegt wat een aanroeper zou kunnen opmerken, wat het onderscheid is dat het logboek eerlijk houdt zonder elke fix op te blazen tot breaking change.

Hoe abonneren aanroepers zich?

Geef ze meer dan één kanaal, want ze hebben andere taken. Een feed voor de developer die alles wil. E-mail voor wie alleen breaking changes wil. Response-headers voor de code zelf, de enige abonnee die nooit vergeet te controleren: de Sunset-header gedefinieerd in RFC 8594 plaatst de pensioendatum in de respons, waar een clientbibliotheek hem kan loggen.

Het kanaal dat de meeste teams overslaan is het directe. Als een aanroeper vorige week het veld gebruikte dat je verandert, weet je wie hij is, en een e-mail naar die accounts is meer waard dan welke uitzending dan ook. Dit is dezelfde discipline als het sluiten van de klantfeedbackloop, toegepast op een wijziging die niemand heeft gevraagd: de betrokkenen worden individueel op de hoogte gebracht, en iedereen krijgt de feed. Een webhook is een vierde kanaal met een eigen faalpatroon dat het waard is te kennen voordat je erop vertrouwt: webhook-changelogs behandelt waarom een payloadwijziging daar stilletjes breekt, zonder aanroeper die de nieuwe vorm kan afwijzen.

Hoe schrijf je een item voor een breaking change?

Begin met de breuk, niet met de reden. Een aanroeper die tien items scant, moet in de eerste zin weten of deze hem werk gaat kosten. Dan de datum, de betrokken versies, de migratie, en de deadline als het oude gedrag verdwijnt in plaats van verandert.

Zet dezelfde inhoud in de deprecation-melding, de response-header en de directe e-mail, consistent geformuleerd, en geef alle vier dezelfde datum. Afwijking daartussen is de fout die een geplande wijziging in een incident verandert, omdat de aanroeper die er maar één las op de verkeerde datum handelt. Wat is een breaking change behandelt de beslissing zelf, en hoe deprecieer je een API behandelt het tijdschema dat erop volgt.

Bij changeloop wordt een API-wijziging een item zodra de pull request wordt gemerged, iemand het concept bewerkt en goedkeurt, en het item wordt gepubliceerd op de feed en de widget op hetzelfde moment dat een aanroeper wiens widgetfeedback het GitHub-issue werd dat de pull request sluit, daarover op dat issue op de hoogte wordt gebracht. De reviewstap is wat hier telt: een API-changelog is een contractueel document, en geen concept zou een aanroeper mogen bereiken zonder dat iemand het gelezen heeft.

FAQ

Heeft elke API-wijziging een changelog-item nodig? Elke wijziging die een correcte aanroeper zou kunnen opmerken, ja, ook de wijzigingen die je intern vindt. Wijzigingen zonder observeerbaar effect op het verzoek of de respons niet, en die toevoegen traint lezers om te scannen zonder te lezen.

Moet de API-changelog in de docs staan of op de marketingsite? In de docs, vlak naast de referentie. De lezer is meestal al daar, en een changelog op de marketingsite krijgt vaak een publiek waarvoor hij niet geschreven is.

Hoe ver terug moet hij gaan? Onbeperkt. Items worden jaren later geciteerd in incidentanalyses, en een afgekapt logboek breekt die links. Pagineer in plaats van te snoeien.

Heb ik een aparte changelog per API-versie nodig? Nee, één logboek met een versieveld per item is makkelijker te lezen en te doorzoeken. Filteren op versie is een functie van de pagina, geen reden om het document te splitsen.

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-voorbeelden