Naar de inhoud
maarten.
Heldere oranje omleidingsbord met voetgangerssymbool leidt het straatverkeer.
Alle stories

API-versiebeheer en breaking changes

Maarten Soetens 12 min lezen

API-versiebeheer bepaalt hoe wijzigingen in een interface doorwerken in bestaande clients. Lees hoe URL- en headerversies verschillen, welke aanpassingen compatibel zijn en hoe je een migratie beheerst zonder afhankelijkheden over het hoofd te zien. Voor robuuste API-koppelingen zijn ook duidelijke contracten en een beheerste migratie belangrijk.

Waarom API-versiebeheer meer is dan een versienummer

Een API is gewoon een afspraak tussen de aanbieder en de software die verbinding maakt. Daar valt niet alleen het endpoint- en veldnamenpatroon onder, maar ook datatypen, foutcodes, authenticatie, paginering, betekenis van waarden. Kleine technische aanpassing? Kan alsnog een hele client ontregelen. Bijvoorbeeld als een veld ineens soms ontbreekt, terwijl jouw code verwacht dat het er altijd is.

Versiebeheer maakt zichtbaar op welk contract een client vertrouwt. Je geeft jezelf de ruimte om aanpassingen gepland te doen, in plaats van plotseling alles tegelijk te breken. Maar een versienummer alleen lost het compatibiliteitsvraagstuk niet. Je hebt duidelijke afbakening nodig: wat valt er nu precies onder een versie, hoe lang werkt die nog, en langs welke route kunnen klanten overstappen? Bij PHP-ontwikkeling helpt een helder contract om wijzigingen beheersbaar te houden.

Bedenk daarom ook vast: zijn het hele API's die een versie krijgen, of slechts losse resources? Of gaat het nog specifieker om de presentatie van data? En wat doe je met andere eigenschappen zoals authenticatie, foutmeldingen? Als je dit niet vooraf verduidelijkt, groeit de rompslomp via uitzonderingen per endpoint en worden documentatie en support onnodig lastig. Dan wordt onderhoud vooral giswerk wanneer een wijziging voor client A wel kan, maar voor client B niet.

API-versies in URL’s: zichtbaar en eenvoudig te routeren

Zet je een versie in de URL, dan staat het versienummer in het pad. Dus zoiets als een prefix vóór of na de resource. Je ziet direct in logs, browsertools, foutcode of documentatie welke variant je doorstuurt. Routers, API-gateways en caches kunnen aan de hand van dat prefix vrij makkelijk de goede richting op sturen. Zeker als er langere tijd meerdere contracten naast elkaar moeten bestaan, werkt het overzichtelijk.

Maar dat je het zo zichtbaar maakt, brengt ook verwarring. Dat prefix lijkt een eigen resource te suggereren, terwijl de inhoud in wezen dezelfde gegevens representeert maar net even anders. En als je een nieuwe versie kiest, moet elke client z'n basis-URL veranderen. Hang je versies aan losse endpoints, dan kunnen wat rare combinaties onstaan: een klant krijgt de nieuwe contractversie voor "klanten" maar blijft op de oude voor "facturen" hangen. Zo krijg je een fragmentatie die lastig te volgen is. Consistente grenzen zijn belangrijk.

Vooral bij publieke API's waar elke client bewust kiest is een URL-versie logisch. Kies je hiervoor, laat dan routering en documentatie gelijk oplopen: dezelfde versie moet hetzelfde betekenen voor alles wat erbuiten valt. Voorkom dat de URL alleen een doorgeefluik is naar altijd de nieuwste code. Als je contract langzaam aanpast zonder het pad te wijzigen, kun je net zo goed geen versies gebruiken; dan verliest het versienummer zijn voorspelbaarheid.

API-versies in headers en media types

Een andere aanpak: laat de client z'n gewenste contract kiezen via een HTTP-header. Dat kan een eigen versieheader zijn, of een media type die in de content negotiation wordt gebruikt. Daardoor verandert de URL niet, maar geef je via je request aan welke voorstelling van de gegevens je wilt hebben. Zo scheid je resource-identificatie van contractversie en sluit het beter aan op API's die netjes gebruikmaken van HTTP-functies.

Maar een minder zichtbare versie is vaak lastiger terug te vinden. Wie uit een log een URL pakt of een foutje napluist, ziet niet vanzelf welke versie is gebruikt. Je moet de gebruikte headers dus consequent loggen, vastleggen, en meenemen bij fouten. Caching vergt aandacht: als de response afhangt van een header, moet die header mee in de cache key, bijvoorbeeld via een juiste Vary-header. Anders kan de client ineens de verkeerde versie uit de cache vissen.

Headers vragen ook om expliciet beleid: wat als een client geen versie meegeeft? Of eentje die niet meer geldt? Zomaar overschakelen op "nieuwste" maakt gedrag afhankelijk van gemaakte wijzigingen en kan compatibiliteit zomaar breken. Laat dus in de documentatie en foutmeldingen zien hoe je versie kiest. Het gaat hier niet puur om smaak; zichtbaarheid, caches, tooling en support beïnvloeden of het gebruik hiervan werkbaar blijft.

Semantische versienummers en contractwijzigingen

Vaak hoor je: semantic versioning werkt met major, minor en patch. Major staat voor contractbreuk, minor voegt functies toe zonder bestaande dingen te breken, en patch is uitsluitend onderhoud zonder contractwijziging. Dat was oorspronkelijk handig voor libraries en ingekapselde services, waarbij elke versie een afgezonderde release is. Maar voordat je zoiets op je API plakt, moet je weten: wat stelt dat nummer hier eigenlijk voor? Een patchnummer in een URL zegt weinig als clients er toch niets mee doen.

Maak dus verschil tussen de implementatieversie en die van het publieke contract. Een interne update doet er soms tientallen keren over voor clients iets nieuws nodig hebben. Maar tot je verbazing kan een ogenschijnlijk kleine wijziging, denk aan een foutcode of een waarde die ineens meer betekent, alsnog het contract raken. Kijk daarom niet naar de hoeveelheid code, maar naar zichtbaar gedrag bij de client.

Check per aanpassing of alle requests en responses zich voor clients nog hetzelfde gedragen. Een optioneel extra veld zal niet zo snel kwaad kunnen, totdat je het verplicht stelt of de client niet tegen ongekende velden kan. Een enum met nieuwe waarde is veilig, behalve als clientcode alle huidige waarden letterlijk uitschrijft. Versienummers helpen structureren, maar zijn geen bliksemafleider voor goed nadenken over daadwerkelijk clientgedrag.

Backward compatible API-wijzigingen beoordelen

Backward compatible klinkt mooi: bestaande clients werken nog gewoon met dezelfde aannames. Maar alleen checken of een endpoint antwoord geeft, zegt niet zoveel. Een nieuw optioneel requestveld is pas riskant als je het verplicht stelt of een standaard verandert. Nieuwe responsevelden lijken geen probleem, tot clients gaan klagen omdat onbekende velden worden afgekeurd, of hun parser heel strikt blijkt te zijn.

Wees alert op aantal en betekenis. Stel: een lijst kon vroeger nooit leeg zijn, en nu ineens wel, dat kun je als client flink merken, ook als het veld als type niet verandert. Hetzelfde geldt voor sortering, nulls, tijdzones, afrondingen, of dat je ineens net andere volgorde krijgt. Zulke afspraken staan vaak niet in het schema, maar clients rekenen er wel op.

Begrijp de context waarin een veld gebruikt wordt. Kijk wie het leest, waar aannames in code zitten, en of je wijziging iets doet met fouten of beveiliging. Leg niet alleen veranderingen, maar ook bestaand gedrag vast dat je wilt behouden: wat betekent een ontbrekend veld, welke statuscode kies je voor een validatiefout? Alleen naar een OpenAPI-schema kijken dekt dit niet af; het draait om wat clients in werkelijkheid verwachten.

Breaking changes herkennen vóór implementatie

Breekt een wijziging? Dan werkt een bestaande client niet meer, tenzij die wordt aangepast. Soms ligt dat voor de hand: een veld is weg of krijgt een nieuwe naam, datatype verandert of het endpoint of de HTTP-methode wijzigt. Maar er zijn ook veranderingen die minder duidelijk zijn: strengere validatie, wisselen van default, andere autorisatie, of statuscodes waar clients iets speciaals mee doen. Beperk je toegestane waarden, dan kun je bestaande data ineens ongeldig maken.

Kijk altijd vanuit beide kanten. Bij een verzoek kan de server zich anders zijn gaan gedragen: een veld weigeren. Bij een respons verwacht de client juist informatie die ineens ontbreekt. Een nieuw verplicht veld kan oude clients breken, terwijl een response-uitbreiding soms alleen clients raakt die stevig op schema’s valideren. Het hangt dus echt af van de soort implementatie die je tegenkomt.

Schrijf reden en impact van een breaking change op voordat je de nieuwe versie in detail bouwt. Soms kun je met een kleine compatibele aanpassing vooruit, door tijdelijk zowel oud als nieuw te ondersteunen; soms is afscheid onvermijdelijk omdat de betekenis helemaal verandert. Houd oude en nieuwe semantiek niet vaag in één formaat: dan interpreteert de ene client hetzelfde veld ineens anders dan de andere. Duidelijke scheiding helpt dit soort verrassingen voorkomen.

Migreren tussen API-versies zonder clients te verrassen

Migratie is meer dan alleen een andere URL of header invullen. Een client moet nieuwe schema’s aan, gewijzigde foutcodes begrijpen en opgeslagen gegevens correct verwerken. Begin daarom met een lijstje van alle consumers. Dat is niet alleen de backend, maar ook mobiele apps, partners, batches, scripts. Een endpoint dat weinig verkeer lijkt te hebben, kan stiekem essentieel zijn als een nachtelijke taak erop draait. Meten van verkeer zegt dus niet altijd welk contract een client werkelijk gebruikt.

Je voorkomt chaos door nieuwe en oude contracten even naast elkaar te laten lopen. Dat vereist heldere routering, gescheiden documentatie en tests die alle veelgebruikte scenario’s zowel voor oud als nieuw afdekken. Als je in stapjes migreert, moet de server goed omgaan met data die door oude en nieuwe clients gedeeld wordt. Interpretatieverschillen in opslag kunnen anders tot merkwaardige bugs leiden.

Maak voor elke client of integratie zichtbaar waar die staat in de migratie. Leg vast welke versie wordt gebruikt en welke requests nog aan oude functies hangen. Alleen een migratiemail sturen geeft weinig zekerheid. Denk ook aan externe klanten of integraties, want hun updatecyclus is vaak langzamer of lastiger te beïnvloeden. Daar loop je nog weleens tegen blokkades aan die niet zomaar weg te nemen zijn. Een freelance developer kan helpen de migratiestappen en afhankelijkheden in kaart te brengen. Zie ook API-rate limits bij het plannen van clients.

Uitfaseren van oude API-versies en compatibiliteit testen

Het uitfaseren van een oude versie vraagt om heldere afspraken: wat is nog beschikbaar, wat wordt aangeraden, wat stopt definitief? Geef die informatie op een vindbare plek: bijvoorbeeld per versie in de documentatie, of in een responseheader. Een waarschuwing meesturen in responses kan extra helpen, maar vervangt geen directe melding aan klanten die nog afhankelijk zijn. Wees concreet: welke functies verdwijnen, welke acties zijn nodig? "Er is een nieuwe versie" zegt klanten te weinig.

Testen van compatibiliteit gebeurt niet alleen met een schema-diff. Die vind schema-wijzigingen als velden, types, verplichtingen. Maar contracttests checken of bestaande verwachtingen van klantsoftware kloppen. Integratietests zijn soms nodig voor zaken als authenticatie, paginering, bijzondere fouten of randgevallen. Geen enkele testwijze pakt alles, dus combineer controles met een inhoudelijke review van kritieke wijzigingen.

Meten is hier essentieel. Registreer aanvragen per versie, client, endpoint en monitor fouten na wijzigingen. Logging moet de gebruikte contractversie vastleggen, maar voorkom dat gevoelige info onnodig wordt bijgehouden. Je haalt een oude versie pas weg als je begrip hebt van het resterende gebruik, en vastlegt hoe je omgaat met uitzonderingen, dus klanten die never nooit meer kunnen of willen aanpassen. Zonder regels blijft er altijd wel ergens een vergeten client hangen of raak je per ongeluk iets kwijt wat nog cruciaal was.

Veelgestelde vragen

Hoe lang moet je een oude API-versie ondersteunen?

Je blijft een oude versie ondersteunen zolang klanten die die kennen die nog niet veilig over kunnen. Er is geen universele termijn: dat hangt af van hoe vaak clients releasen, contractuele afspraken, risico’s, hoe groot de gevolgen van uitval zijn, enzovoort.

  • Geef per versie aan tot wanneer ondersteuning geldt en wanneer deze eindigt.
  • Bied ruim voldoende tijd voor testen en uitrol.
  • Verleng de periode als klanten nog niet konden overstappen of je afhankelijkheden nog niet weg zijn.

Maak duidelijk als je een uitzondering maakt; laat oude versies niet ongezien eindeloos doorlopen.

Hoe kondig je het uitfaseren van een API-versie concreet aan?

Je kondigt uitfasering aan met een heldere datum, uitleg van gevolgen, en een beschrijving van stappen voor elke client die het raakt. Maak onderscheid tussen "niet meer aanbevolen" en "echt afgesloten", dat zijn verschillende momenten waarop gebruikers actie moeten nemen.

  • Vermeld huidige en aanbevolen versies in documentatie.
  • Benoem endpoints, velden of gedrag dat verandert.
  • Meld het rechtstreeks aan bekende klanten en herhaal dit zelfs voor de einddatum.
  • Zet waar zinvol Deprecation- en Sunset-headers in responses als extra signaal.

En gevolgd hiervan: check of klanten het hebben gezien en of hun gebruik daadwerkelijk afneemt.

Moet een SDK dezelfde versie volgen als de API?

Nee, dat hoeft niet. Een SDK krijgt zijn eigen versienummering en releasecyclus, want het is een hulpmiddel voor de client, de API is het servercontract. Soms voeg je nieuwe functies toe in een SDK of los je bugs op zonder dat het contract wijzigt. Omgekeerd kan het zijn dat de API verandert maar er nog geen nieuwe SDK-release klaarstaat.

  • Gebruik dus een eigen versie voor de SDK.
  • Toon in documentatie altijd welke API-versies door welke SDK-release ondersteund zijn.
  • Test zowel handgeschreven als gegenereerde clients op de bedoelde contractversies.

Zo blijft voor ontwikkelaars duidelijk wat waarmee samenwerkt, zonder verwarring tussen nummers met verschillende betekenis.

Kunnen meerdere API-versies op dezelfde backend draaien?

Ja, dat is zeker een optie, mits je op de backend goed onderscheid houdt tussen verschillende contracten. Vaak maak je per versie een adapterlaagje, die aanvragen en responses vertaalt tussen het publieke contract en een vaste interne structuur. Je hoeft dan je werkelijke bedrijfslogica niet elke keer te kopiëren voor elke versie.

  • Zet versie-specifieke validatie en veldnamen in deze adapters.
  • Gebruik één centrale source of truth voor gedeelde data.
  • Test of wijzigingen via versie A ook correct zichtbaar zijn via versie B.

Als de betekenissen of verwerking teveel uit elkaar lopen, kun je alsnog een diepere splitsing nodig hebben. Dwing dan geen gedeelde code af die tot fouten leidt.

Hoe pas je beveiligingsupdates toe op oude API-versies?

Je past noodzakelijke beveiligingsupdates toe op alle ondersteunde versies, zolang je daarbij het afgesproken contract niet onnodig verandert. Een versie die bekende kwetsbaarheden in authenticatie, autorisatie of inputverwerking heeft laat je niet lopen. Maar houd rekening met gedrag van bestaande clients als je ingrijpt en communiceer veranderingen helder.

  • Probeer kwetsbaarheden op te lossen achter de bestaande interface.
  • Test authorisatie en foutafhandeling per versie die nog ondersteund wordt.
  • Maak een notitie als een beveiligingsoplossing een brekende verandering betekent.
  • Beëindig de ondersteuning als een versie echt niet meer veilig te patchen is.

Laat consumenten weten welke versies beveiligingsupdates krijgen. Zo kennen ze het risico als ze lang op oude software blijven zitten.

Foto: Joshua Brown

Portret van Maarten

Maarten

Freelance developer in Nijmegen

Even kennismaken?

Vertel kort wat er speelt. Dan hoor je wat er kan, wat ik anders zou doen en waar AI bij jou wél en niet iets toevoegt. Vrijblijvend.

Het kantoor in Nijmegen
© 2026 maarten.online Sitemap Privacy Algemene voorwaarden
Het kantoor in Nijmegen

Maarten.

Freelance developer in Nijmegen. Liever direct contact? Dat kan ook.

Kennismaken

Laat je gegevens achter, dan kijken we of het klikt. Vrijblijvend en zonder verkooppraat.

Maarten

Stuur een bericht via WhatsApp

Hoi! Waar kan ik je mee helpen?

nu