Een hypotheekacceptatieproces kan stilvallen door één kleine wijziging in een woningdata-API. Denk aan een energielabel dat verdwijnt, of woningwaarde die van een getal verandert in een object. Dezelfde client-code wordt dan geraakt in hypotheekacceptatie, makelaarsoftware, taxatieflows en toepassingen waarin Kadaster-transacties, energielabels en verduurzamingsdata samenkomen.
Backwards compatibility betekent dat bestaande clients met een nieuwe API-versie blijven werken zonder onverwachte uitval of een gewijzigde betekenis van gegevens. Voor teams die woningwaardemodellen, energiegegevens en objectkenmerken integreren, is dat geen detail in de documentatie. Het is een ontwerpkeuze met gevolgen voor releaseplanning, beheer, auditbaarheid en vertrouwen in dossiers.
Waarom backwards compatibility een ontwerpkeuze is voor woningdata
Voor een hypotheekteam begint het probleem vaak niet bij een grote migratie. Een developer past een response aan, een release gaat live en een bestaande parser loopt vast. Als energielabel niet meer op dezelfde plek staat, kan een acceptatieregel niets terugvinden. Als woningwaarde ineens een geneste structuur wordt, moet software die een numerieke waarde verwacht eerst worden aangepast.
De oorzaak is meestal niet alleen slechte code. Meerdere organisaties vertrouwen langdurig op hetzelfde API-contract. Een hypotheekverstrekker gebruikt woningkenmerken in acceptatie, een taxatieplatform haalt referentiewoningen op en een verduurzamingsmodule verwerkt energiegegevens. Als één leverancier zonder overgang een contract breekt, moeten al die afnemers tegelijk reageren.
Praktische regel: behandel backwards compatibility als onderdeel van productontwerp, niet als reparatie nadat klanten klachten melden.
Stabiliteit tegenover onderhoud
Compatibel uitbreiden heeft een prijs. Je houdt oudere velden, documentatie en soms meerdere versies actief. Daardoor kunnen oude interpretaties langer blijven bestaan en wordt testen complexer. Toch kan die tijdelijke beheerslast opwegen tegen een ongeplande wijziging in productie, zeker wanneer dossiers, taxatiewaarden of energiegegevens onderdeel zijn van een controleerbaar proces.
De Nederlandse API Design Rules van Logius koppelen versiebeheer expliciet aan backwards compatibility. Een nieuwe major release is nodig bij backwards-incompatibele wijzigingen. Minor- en patchreleases mogen alleen compatibele veranderingen bevatten, zoals een extra endpoint of een optioneel attribuut. Voor ontwikkelteams is dat een bruikbaar uitgangspunt: ontwerp de uitbreiding eerst zo dat bestaande code niets hoeft te doen.
Een goede versiestrategie beschrijft daarom vooraf welke velden stabiel blijven, hoe nieuwe informatie wordt toegevoegd, wanneer een major release nodig is en hoe afnemers worden geïnformeerd. De developer experience rond API-integratie hoort daar direct bij, omdat duidelijke documentatie en voorspelbare foutafhandeling migratierisico's beperken.
Wat backwards compatibility en breaking changes betekenen
Backwards compatibility betekent dat een bestaande client een latere API-versie kan gebruiken zonder dat de integratie onverwacht stopt of de betekenis van de gegevens verandert. Dat gaat verder dan dezelfde JSON-structuur teruggeven. Ook validatieregels, statuscodes, foutmeldingen en de semantiek van velden moeten voorspelbaar blijven.
Bij woningdata zie je het verschil snel. Een client die bouwjaar als getal verwerkt, kan onverwacht gedrag vertonen wanneer de API een tekstwaarde retourneert. Een parser kan sorteren op tekenvolgorde in plaats van op bouwjaar. Een controle die woningkenmerken gebruikt voor een energieberekening kan daardoor een andere uitkomst krijgen, zonder dat de HTTP-aanroep zelf mislukt.
Drie herkenbare breuken
Een veld verwijderen is een directe breuk. Software die postcode verplicht opslaat of valideert, kan een onvolledig woningobject weigeren. Hetzelfde geldt voor een nieuwe verplichte requestparameter. Oude clients sturen die parameter niet mee en krijgen dan een fout voordat ze hun bestaande proces kunnen uitvoeren.
Een datatype wijzigen lijkt soms onschuldig, maar raakt implementaties diep. bouwjaar: 1985 en bouwjaar: "1985" kunnen voor een mens gelijk lijken. Voor validatie, sortering en database-mapping zijn het verschillende contracten.
De lastigste wijziging betreft betekenis. Stel dat woningwaarde eerst een modelmatige marktinschatting representeert en later ook verwachte renovatiekosten bevat. De naam blijft gelijk, maar hypotheeksoftware gebruikt de waarde dan voor een andere berekening. Dat is functioneel een breaking change.
| Wijziging | Voorbeeld | Gevolg |
|---|---|---|
| Veld verwijderen | postcode verdwijnt uit een woningobject |
Validatie, opslag of dossierverwerking kan mislukken |
| Datatype wijzigen | bouwjaar gaat van getal naar tekst |
Parsers, sortering en controles kunnen anders werken |
| Semantiek wijzigen | woningwaarde bevat ook renovatiekosten |
Acceptatie- en rapportageberekeningen kunnen een andere betekenis krijgen |
| Verplicht maken | Een nieuwe requestparameter is vereist | Oude clients ontvangen een foutmelding |
De veilige standaard is additief: voeg nieuwe velden of endpoints toe, maar wijzig bestaande waarden niet stilzwijgend. De uitleg over backwards-compatible REST-API's beschrijft hetzelfde basisprincipe voor clients die met een eerdere versie zijn gebouwd. Test dus niet alleen of het schema klopt, maar ook of de betekenis van modelwaarde, energielabel en objectkenmerken hetzelfde blijft.
Drie manieren om een woningdata-API te versionen
API-versioning maakt zichtbaar welk contract een client gebruikt. Voor woningdata zijn drie patronen gangbaar. Geen enkele keuze is automatisch goed. De juiste vorm hangt af van hoeveel afnemers je hebt, hoe gateways en caches werken en hoe hypotheek- en makelaarsoftware de versie vastlegt.
Versioning in het URI-pad
Bij path-versioning staat de major versie in de resource-URI, bijvoorbeeld /api/v2/woningwaarde. Een bestaande /api/v1/woningwaarde kan naast v2 blijven functioneren. Dat maakt het patroon begrijpelijk in browserlogs, monitoring en foutanalyses.
Voor een Kadaster Transactie API is dit praktisch wanneer meerdere organisaties dezelfde resource aanspreken en elke client expliciet moet kunnen zien welke contractversie wordt gebruikt. De Nederlandse publieke API-richtlijn schrijft voor dat alleen het major versionnummer in de URI staat. Een major versie wordt opgehoogd wanneer backwards compatibility breekt, terwijl minor- en patchwijzigingen bestaande code niet mogen raken. Zie ook de Nederlandse API Design Rules over URI-versioning.
Een header of queryparameter
Met X-API-Version: 2 of ?version=2 blijft de resource-URI gelijk. Dat kan aantrekkelijk zijn wanneer dezelfde resource verschillende contracten ondersteunt. Het vraagt wel discipline. Headers worden niet in elke client, proxy of monitoringtool even zichtbaar bewaard, terwijl queryparameters in cache-sleutels en logregels terecht kunnen komen.
Media-type versioning
Een client kan een representatie kiezen met bijvoorbeeld Accept: application/vnd.woningdata.v2+json. Deze aanpak past wanneer dezelfde woningresource inhoudelijk verschillende representaties heeft. De richtlijn voor compatibiliteit in RESTful API's noemt media-type versioning als optie wanneer een nieuwe representatie nodig is. Vergeet dan niet de versie-informatie consistent te verwerken in Content-Type en, bij caching, in Vary.
| Strategie | Voorbeeld | Voordelen en aandachtspunten |
|---|---|---|
| URI-path | /api/v2/woningwaarde |
Zichtbaar en eenvoudig te debuggen, maar vraagt beheer van meerdere paden |
| Header of queryparameter | X-API-Version: 2 |
URI blijft stabiel, maar tooling en caching moeten de versie goed bewaren |
| Media-type | Accept: application/vnd.woningdata.v2+json |
Geschikt voor verschillende representaties, met meer afstemming in clients |
Leg de keuze vast in gatewayconfiguratie, OpenAPI-documentatie, contracttests en logging. De versiestrategie voor API's moet voor developers net zo duidelijk zijn als het datamodel zelf.
Strategieën om compatibel uit te breiden zonder migratiedruk
Een woningdata-API kan meestal uitbreiden zonder bestaande klanten direct te laten migreren. De kern is dat nieuwe informatie optioneel blijft en dat een noodzakelijke breuk een gecontroleerd overgangspad krijgt.
Add-only als standaard
Add-only betekent dat je alleen velden, endpoints of optionele attributen toevoegt. Een uitbreiding met extra energiekenmerken kan dan naast bestaande energielabel-velden bestaan. Een hypotheekclient die het nieuwe veld niet kent, negeert het, terwijl een verduurzamingsmodule de extra informatie wel gebruikt.
Dit past bij wijzigingen waarbij de bestaande betekenis intact blijft. Nieuwe NTA 8800-gerelateerde gegevens kunnen bijvoorbeeld in een aanvullend object terechtkomen, zolang bestaande clients niet verplicht worden om dat object te verwerken.
Deprecation met een duidelijke einddatum
Soms moet een veld verdwijnen of wordt een endpoint vervangen. Markeer het oude contract dan formeel als deprecated, publiceer een migration guide en stuur de planning actief naar API-keyhouders. De beheerregels van Logius koppelen lifecyclebeheer aan een deprecation schedule, een changelog en proactieve communicatie.
Voor voorzieningen die landen in de Basisregistratie Adressen en Gebouwen noemt de beschreven Logius-strategie een minimale aankondigingstermijn van zes maanden. Gebruik die termijn als ondergrens voor planning, niet als excuus om pas aan het einde contact op te nemen. Bij woningdata moeten teams bovendien bepalen of de verbeterwinst opweegt tegen de impact op bestaande implementaties.
Dual-write en shadow-verkeer
Bij een grote wijziging laat je v1 en v2 tijdelijk naast elkaar draaien. In shadow-modus roept de router v2 aan zonder het antwoord direct aan de klant te tonen. Je vergelijkt de uitkomsten op echte verzoeken, bijvoorbeeld woningwaardes, transacties of energiegegevens, en onderzoekt verschillen voordat v2 productiegedrag bepaalt.
| Strategie | Wanneer kiezen bij woningdata | Aankondigingstermijn | Belangrijkste risico |
|---|---|---|---|
| Add-only | Nieuwe optionele kenmerken of endpoints | Geen migratie nodig, wel documenteren | Responsegroei kan slecht gedrag in clients blootleggen |
| Deprecation | Veld of endpoint moet gecontroleerd verdwijnen | Minimaal zes maanden voor de genoemde BAG-gerelateerde voorzieningen | Klanten stellen migratie uit |
| Dual-write en shadow-verkeer | Major release met veranderde structuur of rekenkern | Plan communicatie en overlap vooraf | Verschillen tussen versies blijven onverklaard |
De governancekeuze is helder. Logius staat compatibele uitbreidingen toe in minor- en patchreleases, terwijl een brekende wijziging naar een major release hoort. Het Forum Standaardisatie beoordeelde in 2024 een versie van een standaard expliciet op volledige backwards compatibility en stelde vast dat nieuwe verplichte modules een breuk konden veroorzaken. Dat maakt compatibiliteit ook een adoptie- en beheercriterium, niet alleen een technische voorkeur.
Migratie in productie zonder bestaande klanten te breken
Een veilige productiemigratie geeft developers controle over timing, klantselectie en terugval. Laat een major release daarom niet in één stap het hele hypotheek- of makelaarlandschap overnemen.
Stap 1, documenteer elke breuk
Maak een changelog waarin elke wijziging gekoppeld is aan een ticket, impactanalyse en migratieactie. Noteer bijvoorbeeld dat taxatiewaarde wordt vervangen door modelwaarde, waarom dat gebeurt en welke response clients moeten verwerken.
Checklist voor developers
- Vergelijk het oude en nieuwe OpenAPI-schema.
- Beschrijf datatype-, validatie- en betekeniswijzigingen.
- Voeg een voorbeeldresponse en foutscenario toe.
Stap 2, laat versies parallel draaien
Publiceer v2 naast v1 en maak de routering expliciet. Een client moet via pad of header bewust een versie kiezen, niet door een ongedocumenteerde standaardwaarde.
Checklist voor developers
- Controleer dat v1 dezelfde resultaten blijft leveren.
- Registreer welke klant en welke versie een request gebruikt.
- Test terugval naar v1 bij problemen in v2.
Stap 3, geef een deprecation schedule
Zet de einddatum in het API-portaal, de v1-documentatie en de OpenAPI-specificatie. Gebruik response-headers om afnemers aan de oude status te herinneren. De overgangstermijn moet aansluiten op de afgesproken governance en op de releasekalender van klanten.
Stap 4, activeer per klant
Feature flags of tenantconfiguratie maken het mogelijk om early adopters op v2 te zetten, terwijl lopende acceptaties op v1 blijven. Combineer dat met contracttests en een reproduceerbare testset. De principes achter continuous integration voor API-teams helpen om schemawijzigingen vroeg in de buildstraat te signaleren.
Stap 5, faseer uit
Wanneer de overgang afgerond is, retourneert v1 volgens de afgesproken procedure een beëindigingsstatus, bijvoorbeeld HTTP 410 Gone. Log welke clients nog bellen, communiceer de blokkade van nieuwe API-keys en houd een beperkte grace-period aan wanneer dossiers nog aantoonbaar doorlopen.
Uitrolregel: een migratie is pas klaar wanneer je weet wie v1 nog gebruikt, waarom die client nog niet is overgestapt en welke terugvalprocedure het team uitvoert.
Praktijkvoorbeeld een makelaarplatform dat v1 en v2 naast elkaar draaide
Voorbeeld BV, een middelgroot makelaarsoftwareplatform, gebruikte een Woningwaarde API v1 voor taxatiewaarde, energielabel en BAG-afgeleide kenmerken in één payload. Het team ontwikkelde v2 omdat de energielabelgegevens een aparte resource nodig kregen en de rekenkern veranderde. Daarom werd taxatiewaarde in v2 hernoemd naar modelwaarde, zodat de naam beter aansloot op de nieuwe betekenis.
De migratie werd georganiseerd als dual-write. V1 bleef zes maanden in productie, terwijl v2 eerst in shadow-modus draaide. Echte taxatieverzoeken riepen op de achtergrond ook v2 aan. Het team vergeleek de antwoorden met delta-logica, waarbij het niet alleen controleerde of waarden verschilden, maar ook of het verschil verklaarbaar was door het nieuwe contract.
Waar het bijna misging
Een corporatieklant activeerde per ongeluk massaal het /v2/-pad. Een junior developer had het pad uit de nieuwe SDK overgenomen zonder te controleren dat het v2-endpoint nog geen afgesproken SLA had. Tijdens piekuren crashte v2, waardoor de migratie buiten de geplande klantgroep dreigde te vallen.
De routerlaag stuurde het verkeer terug naar v1. Voorbeeld BV kon v2 harden, de monitoring verbeteren en de SDK aanpassen voordat de echte cutover plaatsvond. De belangrijkste les zit niet in het naast elkaar draaien zelf, maar in de combinatie van versieselectie, klantisolatie en terugval.
| Beslissing | Effect in deze migratie |
|---|---|
| V1 bleef beschikbaar | Bestaande klanten hoefden niet direct te wijzigen |
| V2 liep in shadow-modus | Het team kon verschillen met echte verzoeken onderzoeken |
| Routering koos per klant | Een fout bij één afnemer verspreidde zich niet automatisch |
| SDK werd gecontroleerd | Een onbedoelde activatie werd zichtbaar als release-risico |
Dit voorbeeld is geanonimiseerd en illustreert een ontwerpaanpak, geen prestatieclaim. Voor woningwaardemodellen blijft bovendien gelden dat een technisch gelijk antwoord niet automatisch dezelfde zakelijke betekenis heeft. Documenteer dus altijd welke data een client gebruikt voor acceptatie, taxatie of verduurzamingsadvies.
Wanneer backwards compatibility juist niet de juiste keuze is
Backwards compatibility past niet bij elke situatie. Soms maakt het vasthouden aan een oud contract het risico groter, bijvoorbeeld wanneer een beveiligingsprobleem in een authenticatieveld van een Kadaster-koppeling direct ingrijpen vereist. Een compatibele tussenlaag kan dan langer kwetsbare logica laten bestaan.
Een major release is ook verdedigbaar bij een structureel verkeerd datamodel. Als klanten een veld nooit consistent konden gebruiken, kan een schone nieuwe resource beter zijn dan een hybride model met uitzonderingen. Hetzelfde geldt wanneer regelgeving of een herziening van NTA 8800 een functie inhoudelijk overbodig maakt, of wanneer een organisatie overstapt op een fundamenteel ander protocol.
Een compacte advieskaart
| Situatie | Voorkeurskeuze |
|---|---|
| Nieuwe optionele woningkenmerken | Add-only uitbreiding |
| Veld moet verdwijnen, maar risico is beheersbaar | Deprecation en migratiepad |
| Nieuwe rekenkern of nieuw datamodel | Parallelle major release met shadow-verkeer |
| Ernstige kwetsbaarheid of wettelijke noodzaak | Directe breuk, met duidelijke communicatie |
De Logius- en Forum Standaardisatie-principes geven een bruikbaar kader: compatibel uitbreiden waar dat kan, expliciet breken waar dat nodig is en bestaande implementaties niet zonder afweging tot migratie dwingen. Communiceer bij een onvermijdelijke major release precies wat breekt, waarom uitstel onverantwoord is, hoe lang de oude versie blijft werken en welke testdata afnemers krijgen.
Veelgestelde vragen over API-versioning voor woningdata
Hoelang moet een deprecation-periode duren voor een woningdata-API?
Voor de genoemde voorzieningen die in de Basisregistratie Adressen en Gebouwen landen, beschrijft Logius een minimale aankondigingstermijn van zes maanden. Gebruik die termijn als ondergrens en stem de werkelijke planning af op releasecycli, auditmomenten en lopende hypotheek- of taxatiedossiers.
Hoe test je backwards compatibility vóór de uitrol?
Gebruik contracttests tegen v1 en v2, voer schema-diffing uit en speel representatief productieverkeer opnieuw af in een veilige omgeving. Controleer bij de Kadaster Transactie API of Woningwaarde API ook statuscodes, foutafhandeling en betekenis van waarden, niet alleen de JSON-vorm.
Mag je een nieuw verplicht veld toevoegen aan een bestaande energielabel-resource?
Niet zonder bestaande clients te breken. Voeg het veld optioneel toe, geef een nieuwe resourcevariant uit of publiceer een major versie wanneer het veld noodzakelijk is voor elk request.
Wat doe je als een afnemer niet migreert?
Maak eerst zichtbaar welke client nog v1 gebruikt en bied technische migratie-informatie. Daarna kun je de afgesproken uitfasering uitvoeren, eventueel met betaalde verlengingsondersteuning, een beperkte grace-period of een technische blokkade, zolang je dit vooraf duidelijk communiceert.
Altum AI biedt woningdata via API's voor onder meer woningwaarde, Kadaster-transacties, energielabels en woningkenmerken, zodat jullie versiecontracten gecontroleerd kunnen integreren in hypotheek- en makelaarsoftware. Test de beschikbare integratieopties en sandbox via Altum AI en bespreek welke versiestrategie past bij jullie dataketen.