Een hypotheekaanvraag staat klaar voor beoordeling. De woningdata komt via een API binnen, de waarderingslogica verwacht een bekend response-schema en de acceptatiestraat draait zonder handmatige tussenkomst. Dan verschijnt de release-notitie: een veld wordt verplicht. Voor de developer lijkt het een kleine contractwijziging. Voor de keten kan het betekenen dat een batch faalt, een object niet meer gematcht wordt en een dossier blijft wachten.

API versioning maakt zo'n compatibiliteitsgrens expliciet. Je legt vast welke client welk contract gebruikt, hoe wijzigingen worden aangekondigd en wanneer een oude versie verdwijnt. Dat is voor woningdata geen theoretische API-hygiëne. Banken, hypotheekverstrekkers, taxateurs en verzekeraars bouwen processen op gegevens over waarde, WOZ, energie, objectkenmerken en transacties. Een onvoorziene wijziging raakt dan niet alleen code, maar ook acceptatie, taxatie en auditbaarheid.

In dit artikel verbind ik API versioning aan een woningdata-integratie, met Nederlandse richtlijnen, beslisregels voor breaking changes en concrete HTTP-voorbeelden. De voorbeelden gebruiken Altum AI als illustratieve API-laag voor woningdata en AI-inzichten over waarde, energie en verduurzaming.

Waarom API versioning beslist over de levensduur van je woningdata-integratie

Een developer bij een hypotheekverstrekker heeft de woningdata-integratie live gezet. Aanvragen stromen binnen, een taxatiebatch haalt woningkenmerken op en een koppeling met de objectregistratie matcht records op basis van een oppervlakveld. Dan verschijnt de release-notitie: het veld wordt in het volgende contract verplicht.

Een kleine contractwijziging kan de hele keten raken. Requests zonder het veld krijgen een foutresponse, de batch stopt halverwege en de objectmatch valt terug op een pad dat niet is uitgevoerd. Een dossier blijft staan, terwijl het team moet uitzoeken welke consumers al met de nieuwe regels werken.

API versioning maakt die compatibiliteitsgrens zichtbaar. Je koppelt een release aan een contractversie, legt vast welke client welke versie gebruikt en plant de overgang voordat oude clients breken. Zonder die afspraak kan een nieuwe release voor de provider als verbetering voelen, terwijl een hypotheekteam verkeerde of onvolledige taxatiewaarden toont.

Praktische regel: behandel een API-contract voor woningdata als een ketenafspraak. Een wijziging is pas veilig wanneer je weet welke clients ervan afhankelijk zijn.

Een bruikbaar releaseproces bevat daarom een versienummer, changelog, OpenAPI-specificatie en migratiepad. De developer experience van Altum AI hoort bij de integratie-ervaring, maar versioning blijft een gedeelde verantwoordelijkheid van provider en consumer. De consumer moet versies expliciet kiezen en testen. De provider moet wijzigingen aankondigen en oude contracten voorspelbaar uitfaseren.

De Nederlandse context geeft hiervoor richting via de API Design Rules. Voor een woningdata-API betekent dat: documenteer de compatibiliteitsgrens, leg versie-informatie vast in de request en geef consumenten tijd om te migreren. Een major-versie in het URI-pad en een volledige versie in de API-Version-header kunnen die keuze controleerbaar maken. Plan de migratie vóór het einde van de afgesproken overgangsperiode en houd bij welke systemen nog afhankelijk zijn van het oude contract. Zo blijft een wijziging beheersbaar voor development, operations en compliance.

Wat API versioning is en hoe semver werkt voor woningdata-endpoints

API versioning is het expliciet benoemen van de compatibiliteitsgrens van een API-contract. De client weet welke vorm van request en response hij gebruikt, terwijl de server nieuwe functionaliteit kan ontwikkelen zonder bestaande consumers onverwacht te breken.

Voor een HTTP-API kun je Semantic Versioning gebruiken in het formaat major.minor.patch. De betekenis is eenvoudig:

• Major: verhoog deze bij een breaking change, bijvoorbeeld het verwijderen van een responseveld of het wijzigen van de betekenis van een waarde.
• Minor: gebruik deze voor backward-compatible functionaliteit, zoals een nieuw optioneel taxatieveld.
• Patch: pas deze toe voor een foutcorrectie of tekstuele verbetering die het parsinggedrag niet verandert.

Neem een woningwaarde-endpoint:

GET /v2/woningen/0363100012345678/waarde
API-Version: 2.0.0
Accept: application/json

Een response in 2.0.0 kan er zo uitzien:

{
  "bagId": "0363100012345678",
  "waarde": 425000,
  "waardePeildatum": "2026-01-01"
}

In 2.1.0 voeg je bijvoorbeeld een optioneel veld toe:

{
  "bagId": "0363100012345678",
  "waarde": 425000,
  "waardePeildatum": "2026-01-01",
  "energielabelPredicted": "B"
}

Een client die onbekende velden negeert, kan met dezelfde major-contractgrens blijven werken. De volledige versie staat in de header, terwijl de URI op /v2/ blijft. De Logius API Design Rules beschrijven precies deze combinatie: Semantic Versioning in de vorm major.minor.patch, alleen major in de URI en de volledige versie in API-Version.

Semver is een denkkader, geen zelfstandig protocol. Je moet per resource bepalen wat breaking betekent. Een nieuwe optionele property is vaak veilig, maar alleen als clients onbekende properties correct verwerken. Een wijziging van waarde van eurobedrag naar een geneste structuur is niet veilig, ook niet wanneer je het versienummer klein houdt.

Voor een OpenAPI-first team hoort de versie in de specificatie, documentatie, contracttests en release-notities terug te komen. De API-documentatie van Altum AI is een logisch startpunt om requestvormen, responsevelden en beschikbare endpoints naast je eigen contracttests te leggen.

Drie versioningsstrategieën naast elkaar voor de Altum AI API

Er bestaat geen universeel juiste plaats voor een API-versie. Voor woningdata telt vooral of developers, gateways, logs en caches de versie eenvoudig kunnen herkennen. De drie meest gebruikte varianten zijn URI-path versioning, header versioning en query-parameter versioning.

URI-path versioning

Met /v2/woningen/{bagId}/waarde ziet iedereen direct welke major-versie wordt aangeroepen. Gateways kunnen routes expliciet scheiden, logs zijn leesbaar en CDN- of reverse-proxy-caches kunnen de URI als cache-key gebruiken. Het nadeel is dat consumers hun URL moeten aanpassen bij een nieuwe major.

Header versioning

Header versioning houdt de resource-URL stabiel:

GET /woningen/0363100012345678/waarde
Accept: application/vnd.altum.woningdata.v2+json

Dit houdt versioning in de content-negotiationlaag. De URL oogt schoon, maar een developer die alleen naar requestregels in een dashboard kijkt, mist sneller de relevante versie. De cache moet bovendien correct rekening houden met de Accept-header.

Query-parameter versioning

Een queryparameter is makkelijk te testen en kan aansluiten op bestaande routering:

GET /woningen/0363100012345678/waarde?version=2

Toch leidt deze aanpak sneller tot onduidelijkheid in caching, analytics en standaardwaarden. Een ontbrekende parameter kan bovendien tot een onbedoelde fallback leiden. Voor hypotheekketens kies ik daarom meestal voor een zichtbare major in het pad, gecombineerd met de volledige API-Version-header.

Nederlandse API Design Rules als kompas voor versiebeheer

In een hypotheekteam werkt versioning als een contract met afnemers. De Nederlandse API Design Rules geven daarvoor een herkenbaar kader: zet de major-versie in het basispad, stuur de volledige Semantic Versioning-versie mee via API-Version, en leg backward compatibility en uitfasering vooraf vast. Voor een Altum AI-request kan dat er zo uitzien:

GET /v2/woningen/0363100012345678/waarde
API-Version: 2.1.0
Accept: application/json
Authorization: Bearer <token>

De URI markeert de compatibiliteitsgrens. De header maakt de precieze release zichtbaar. Routing, documentatie en contracttests kunnen daardoor op /v2/ werken, terwijl logging, support en releasebeheer ook minor- en patchwijzigingen herkennen. Een client weet zo welke major hij gebruikt, zonder dat elk onderhoudsrelease een nieuwe route vereist.

Zo toets je dit tijdens een API-review

Controleer bij elke release:

• URI: staat de major-versie in het basispad?
• Header: bevat iedere response API-Version met major, minor en patch?
• Contract: is de OpenAPI-beschrijving bijgewerkt?
• Compatibiliteit: blijven bestaande requests verwerkbaar?
• Lifecycle: zijn overgang, communicatie en uitfasering vastgelegd?

Dit kader past bij publieke en semipublieke ketens waarin BAG-, WOZ- en Kadasterdata samenkomen met afgeleide woningkenmerken. Leg het besluit vast in architectuurbesluiten, contracttests en releasecommunicatie. De uitleg over voldoen aan de API Design Rules verbindt OpenAPI 3.0.x met Semantic Versioning. Teams moeten daarom expliciet bepalen wanneer een toevoeging minor blijft en wanneer het contract voor consumers verschuift.

Wanneer is een wijziging breaking en wanneer niet

Een wijziging is breaking wanneer een bestaande client de response niet meer veilig kan verwerken of de betekenis van de data verandert. Kijk dus niet alleen naar de code die de provider verandert. Kijk naar parsers, validaties, datamodellen, businessregels en rapportages aan de consumerkant.

Bij een woningwaarde-endpoint is het verschil concreet:

GET /v1/properties/abc123/valuations
API-Version: 1.2.0

{
  "propertyId": "abc123",
  "oppervlakte_m2": 92,
  "bouwjaar": "1998",
  "waarde": 425000
}

Een breaking variant kan er zo uitzien:

GET /v2/properties/abc123/valuations
API-Version: 2.0.0

{
  "propertyId": "abc123",
  "oppervlakte": 92,
  "bouwjaar": 1998,
  "waarde": {
    "bedrag": 425000,
    "valuta": "EUR"
  }
}

Hier zijn meerdere contracten gewijzigd. oppervlakte_m2 is hernoemd, bouwjaar heeft een ander datatype en waarde heeft een andere structuur. Een client die een string verwacht of rechtstreeks waarde als getal opslaat, kan falen.

Een nieuwe enumeratiewaarde vraagt extra aandacht. Die kan backward-compatible zijn wanneer clients onbekende waarden negeren. Een client met een gesloten lijst, bijvoorbeeld alleen bekende energielabelwaarden, kan alsnog breken. Leg daarom in het contract vast of consumers extensie moeten verdragen.

Beslisregel: verander je de naam, het datatype, de structuur, de verplichting of de semantiek van bestaande data, behandel de wijziging als potentieel breaking. Laat een contracttest het besluit bevestigen.

Deprecatie en migratie in zeven stappen voor stabiele ketens

Een major-versie uitbrengen zonder migratiepad verschuift het risico naar je consumers. Een gecontroleerde deprecatie-flow maakt de overgang zichtbaar en meetbaar. Gebruik hiervoor een vast playbook.

1. Markeer de oude route als deprecated. Voeg in de OpenAPI-specificatie een deprecation-markering toe en leg de sunsetdatum vast. Beschrijf welke nieuwe route de vervanger is.

2. Zet lifecycle-informatie in de response. Laat v1 programmatisch melden dat de route wordt uitgefaseerd:

HTTP/1.1 200 OK
Content-Type: application/json
API-Version: 1.4.0
Deprecation: true
Sunset: 2027-06-30

3. Publiceer een migration-gids. Documenteer veldmapping, gewijzigde statuscodes, nieuwe validaties en request- en responsevoorbeelden op de technische documentatie van Altum AI.

4. Informeer API-consumers. Gebruik e-mail voor geregistreerde contactpersonen, een changelog en waar mogelijk een webhook. Een header bereikt code, communicatie bereikt mensen.

5. Plan de overlap. De Nederlandse richtlijn noemt een overgangsperiode van 1 jaar voor oude en nieuwe versies, zoals vastgelegd in de API-strategie voor Nederlandse API's. Plan je tests en releasekalender binnen die periode.

6. Bied parallelle testmogelijkheden. Laat hypotheekteams v1 en v2 in een sandbox naast elkaar aanroepen. Zo kunnen ze contracttests, adapters en acceptatieregels vroeg controleren.

7. Monitor per consumer. Meet welk verkeer nog op v1 zit, welke foutcodes optreden en welke integraties niet reageren op de migratieberichten. Spreek grootverbruikers gericht aan voordat de sunsetdatum bereikt is.

Het interne API-stuurteam kan per release controleren of de OpenAPI-diff is beoordeeld, de headers werken, consumers zijn geïnformeerd, de sandbox beschikbaar is en het rollback-plan getest is. Voor vragen over implementatie en migratie hoort ook een duidelijk technisch supportproces bij het lifecyclebeleid.

Praktijkvoorbeeld migratie van woningwaarde v1 naar v2 bij een hypotheekverstrekker

Een geanonimiseerde hypotheekverstrekker migreerde in drie maanden van woningwaarde v1 naar v2. Het team wilde de bestaande acceptatiestraat niet in één keer omzetten en gebruikte daarom een feature flag om 5% van de taxatieaanvragen via /v2/woningwaarde te routeren. De waarde komt uit het aangeleverde praktijkvoorbeeld en is niet zelfstandig geverifieerd.

Tijdens de canary-fase vergeleken developers de responsevelden veld voor veld. Voor de eindwaarde hanteerde het team een tolerantie van 0,5% voordat de uitrol werd verbreed. Ook deze waarden zijn onderdeel van het aangeleverde praktijkvoorbeeld, niet van een externe bron.

Waar de migratie vastliep

De eerste problemen zaten niet in de route, maar in de aannames van de consumer:

• Een datumveld verschoof van een stringrepresentatie naar een ISO-8601-datatype.
• V2 introduceerde een nieuw subobject voor het energielabel.
• De eigen adviesmotor verwachtte nog de oude veldnaam.
• De staging-tests dekten het nieuwe responsepad aanvankelijk niet volledig af.

Het team koos niet voor een snelle wijziging in iedere downstream-service. In plaats daarvan bouwde het een adapterlaag die v2 vertaalde naar het interne model zolang de rest van de keten nog op de oude naam werkte. Canary-deployments in staging maakten het mogelijk om de adapter, validaties en foutafhandeling apart te testen.

V1 kreeg deprecation-headers. Een dedicated Slack-kanaal met de API-partner bundelde vragen over veldmapping, logging en afwijkende responses. Daardoor bleven technische beslissingen centraal terug te vinden, in plaats van verspreid over losse gesprekken.

Het praktijkvoorbeeld eindigde volgens de aangeleverde casus met een 40% kortere doorlooptijd van taxatieaanvraag tot bindend aanbod, een foutpercentage van 0,8% naar 0,1% en een cut-over zonder klacht-tickets. Deze uitkomsten zijn niet voorzien van een openbare bron en moeten daarom als casusresultaten van het voorbeeld worden gelezen, niet als algemene verwachting voor iedere migratie.

De les zit vooral in de werkwijze. Een feature flag beperkt de blast radius, een adapter beschermt bestaande businesslogica en veld-voor-veld-contracttests maken verschillen zichtbaar voordat ze productie raken.

Checklist en veelgestelde vragen over API versioning

Een release is pas klaar wanneer het contract, de consumers en de lifecycle samen zijn beoordeeld. Gebruik deze checklist voor woningdata-endpoints:

1. Contract-lock: leg request en response vast.
2. Semver-beslissing: bepaal major, minor of patch.
3. ADR-update: documenteer het architectuurbesluit.
4. Altum AI sandbox-validatie: test de gekozen versie naast de bestaande route.
5. Deprecation-header: markeer de oude versie programmatisch.
6. Sunsetdatum: publiceer de uiterste einddatum.
7. Gebruiksmeting: monitor verkeer per versie en consumer.
8. Migratiedocumentatie: voeg veldmapping en voorbeelden toe.
9. Clientnotificatie: informeer geregistreerde contactpersonen.
10. Testvalidering: voer contract-, integratie- en regressietests uit.
11. Rollback-plan: beschrijf hoe je veilig terugschakelt.
12. Post-release monitoring: volg foutcodes en afwijkende responses.

Veelgestelde vragen

Wat is het verschil tussen URI-prefixing en de API-Version-header?

De URI, bijvoorbeeld /v2/, maakt de major-contractgrens zichtbaar en ondersteunt duidelijke routing. De API-Version-header bevat de volledige major.minor.patch-versie voor precieze release-identificatie.

Kan een patchwijziging toch breaking zijn?

Ja. Semver helpt alleen wanneer je de compatibiliteitsregels consequent toepast. Een wijziging die je als patch labelt maar een bestaand datatype, veld of parsinggedrag verandert, kan alsnog clients breken.

Hoe lang blijft een oude versie actief?

De Nederlandse API Design Rules voorzien in een overgangsperiode van 1 jaar voor oude en nieuwe versies, zoals eerder beschreven. Leg de concrete sunsetdatum altijd vast in documentatie en responses.

Hoe test je v1 en v2 in één CI-pipeline?

Maak per versie een OpenAPI-contract, voer dezelfde functionele scenario's uit waar dat inhoudelijk kan en voeg versie-specifieke assertions toe. Test daarnaast de adapterlaag en foutresponses.

Wat doe je als een consumer niet migreert?

Gebruik usage-monitoring om de consumer te identificeren, stuur gerichte communicatie en bied migratiehulp. Laat de sunsetdatum niet stilzwijgend verschuiven, maar wijzig haar alleen via een gedocumenteerd governancebesluit.

Altum AI biedt API's voor herleidbare woningdata en AI-inzichten over onder meer woningwaarde, energie en verduurzaming, met documentatie voor integratieteams. Bezoek Altum AI om de beschikbare API's en testmogelijkheden te bekijken en plan versioning meteen mee in jullie woningdata-architectuur.