Hoe je een API-migratiegids schrijft

Een API-migratiegids is het document dat van een breaking change een checklist maakt in plaats van een storing: wat er veranderde, wat je eraan doet, en tegen wanneer. Een changelog-regel kan een breaking change in twee zinnen noemen; een migratiegids is wat een aanroeper echt opent wanneer die twee zinnen zeggen “dit breekt jou” en ze precies moeten weten wat te wijzigen. De regel publiceren zonder de gids is hoe een aanroeper over een breaking change hoort via een supportticket in plaats van via het document dat geschreven is om dat te voorkomen.

Wat is een API-migratiegids?

Een stap-voor-stap document dat een aanroeper van de oude vorm van een API naar de nieuwe brengt, geschreven voor iemand met code om te wijzigen, niet voor iemand die nog beslist of de API wordt gebruikt. Dat onderscheid telt: een migratiegids gaat uit van een bestaande integratie en bestaand productieverkeer, dus moet hij rollback, gedeeltelijke migratie, en hoe je weet of de migratie lukte behandelen, niets daarvan hoeft een gids voor een eerste integratie te dekken.

Een migratiegids staat meestal tussen de laatste twee in: een deprecation-melding start een klok, en de migratiegids is wat een aanroeper volgt voordat die klok afloopt.

Wanneer heeft een verandering een migratiegids nodig, en niet alleen een changelog-regel?

Wanneer er meer dan één stap zit tussen het oude en het nieuwe gedrag, of wanneer de verandering genoeg aanroeppunten raakt dat een aanroeper meer heeft aan een uitgewerkt voorbeeld dan aan een beschrijving. Wat is een breaking change, en hoe breng je die uit behandelt de test of een verandering breaking is; is het antwoord ja, dan is de tweede vraag of de fix een wijziging van één regel is of een echte migratie. Een hernoemd veld kan een aanroeper alleen met de changelog-regel afhandelen. Een verandering in authenticatie, paginering of foutafhandeling verdient bijna altijd een gids, omdat de juiste vervangende code niet vanzelf spreekt uit een zin lange beschrijving.

Wat moet een migratiegids bevatten?

Vijf dingen, en een ervan overslaan is hoe een gids een pagina wordt die een aanroeper één keer leest en dan terugvalt op vallen en opstaan. De oude code, getoond zoals die echt in een project zou verschijnen. De nieuwe code, op dezelfde manier getoond, niet als abstracte beschrijving van het verschil. Wat er breekt als er niets verandert, duidelijk gezegd, want “niets” is een geldig en gewoon antwoord dat een aanroeper toch expliciet moet horen. Een manier om te verifiëren dat de migratie werkte, zoals een responsveld of een statuscode om te checken. En een tijdlijn: wanneer het oude gedrag stopt met werken, en of beide vormen ondertussen beschikbaar zijn.

## Munteenheidvelden migreren van float naar integer (v3.0.0)

Voor:
  { "amount": 19.99 }

Na:
  { "amount": 1999 }  // kleinste munteenheid (centen)

Wat verandert: `amount` is nu een geheel getal in de kleinste
eenheid van de accountvaluta. Code die `amount` als float leest,
leest vanaf 1 oktober 2026 een 100x te grote waarde.

Verifiëren: na migratie moet een bedrag van $19,99 gelezen worden als
`amount: 1999`, niet als `amount: 19.99`.

Tijdlijn: v2 blijft floats teruggeven tot 15 januari 2027. v3 geeft
gehele getallen terug vanaf lancering. Beide versies zijn nu live.

Elk van die vijf dingen beantwoordt een vraag die een aanroeper anders zou moeten gokken of aan support moeten stellen, en dat is precies de kost die een migratiegids bespaart.

Wie zou hem moeten schrijven, en wanneer?

Wie de verandering ontwierp, op het moment dat die uitkomt, niet een supportteam dat hem later uit tickets reconstrueert. Wie de beslissing nam weet op welke delen van het oude gedrag niemand had moeten vertrouwen en welke een toevallig contract waren; een gids die later door iemand zonder die context wordt geschreven, legt het voor de hand liggende te veel uit of mist juist het ene randgeval dat mensen echt breekt. De gids en de changelog-regel die de breaking change aankondigt zouden samen moeten verschijnen, waarbij de regel naar de gids linkt in plaats van hem te herhalen.

Hoe verhoudt dit zich tot versionering en de API-changelog?

Direct: een migratiegids is de gedetailleerde versie van wat een MAJOR-regel in semantic versioning en je changelog slechts in één zin samenvat. De changelog-regel zegt dat een verandering breaking is en ruwweg wat er veranderde; de migratiegids is de link die die regel zou moeten dragen. API-changelog: wat te publiceren en wie het leest noemt de migratiegids als een van vijf documenten die een API onderhoudt, elk beantwoordt een andere vraag; dit is degene die “hoe kom ik echt van A naar B” beantwoordt, en verdient zijn eigen pagina juist omdat dat antwoord meestal te lang is voor een changelog-regel.

Hoe lang zou een migratiegids gepubliceerd moeten blijven?

Minstens zolang het oude gedrag bereikbaar is, en idealiter ook daarna. Een aanroeper die achttien maanden te laat migreert, na drie deprecation-meldingen te hebben genegeerd, heeft de gids nog steeds nodig, en hem verwijderen op de dag dat het oude gedrag wordt uitgeschakeld garandeert alleen dat de aanroeper die hem het hardst nodig heeft hem niet vindt. Houd hem op een stabiele URL en werk de tijdlijnsectie bij in plaats van de pagina in te trekken. De eigen upgradegids van Stripe is een publiek voorbeeld van dit patroon: één pagina, release na release actueel gehouden, in plaats van een nieuw document per versie dat verouderd raakt zodra de volgende verschijnt. Jullie eigen gids hoort ergens even vindbaar, naast de docs die een aanroeper toch al leest, in plaats van begraven in een blogarchief.

FAQ

Heeft elke breaking change een migratiegids nodig? Nee. Een verandering die een aanroeper alleen met de changelog-regel kan oplossen, zoals een enkel hernoemd veld met een voor de hand liggende vervanging, heeft geen aparte gids nodig. Een verandering die meerdere aanroeppunten raakt of een uitgewerkt voorbeeld nodig heeft, wel.

Hoort een migratiegids bij de API-documentatie of in de changelog? Bij de documentatie, gelinkt vanuit de changelog-regel. De regel is wat een abonnee eerst ziet; de gids is wat ze nodig heeft zodra ze besluit te handelen, en hoort naast het referentiemateriaal dat een aanroeper al gebruikt.

Wat is het verschil tussen een migratiegids en een deprecation-melding? Een deprecation-melding zegt dat iets gaat verdwijnen en tegen wanneer. Een migratiegids zijn de instructies over wat daaraan te doen. Een deprecation-melding zonder gelinkte migratiegids geeft een aanroeper een deadline zonder te zeggen hoe die te halen.

Moeten oud en nieuw gedrag beide gedocumenteerd zijn tijdens een migratievenster? Ja, indien mogelijk op dezelfde pagina, zodat een aanroeper precies ziet wat er veranderde in plaats van het samen te stellen uit twee aparte documenten die op verschillende momenten zijn geschreven.

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