De API bereidt zich voor op versiebeheer

Een breaking change in onze API vereist op dit moment een directe aanpassing in je integratie op het moment dat wij de verandering uitrollen. Daar komt verandering in: we stappen over op datumgebaseerd versiebeheer. Versies gelden per endpoint: een endpoint krijgt alleen een nieuwe versie als het een breaking change heeft.

Als voorbereiding hierop heeft de API nu een nieuwe request-header en twee nieuwe response-headers:

• Met de request-header X-API-Version geef je een datum mee. Je krijgt dan de laatste versie die op of vóór die datum is gepubliceerd.
• De response-header X-API-Version-Matched geeft terug welke versie dat is geworden.
• De response-header X-API-Version-Latest geeft aan wat de laatste versie is; als deze overeenkomt met X-API-Version-Matched, zit je op de nieuwste API.

Bijvoorbeeld:

GET /connections/... HTTP/1.1
X-API-Version: 2026-08-03

HTTP/1.1 200 OK
X-API-Version-Matched: 2026-07-06
X-API-Version-Latest: 2026-09-10

In dit voorbeeld is de versie in het request vastgezet op 3 augustus. De gebruikte versie is 2026-07-06: de laatste versie op of vóór 3 augustus. Was er op 3 augustus zelf een versie gepubliceerd, dan had je die gekregen. Er is al een nieuwere versie 2026-09-10, maar je request wordt afgehandeld zoals het endpoint werkte op de datum die je opgaf.

Naast een datum kun je in X-API-Version ook latest meegeven. Je wordt dan niet vastgepind op een versie en krijgt altijd de nieuwste API. Dit geldt ook als je de header helemaal weglaat.

Zolang de API nog in bèta is, geven X-API-Version-Matched en X-API-Version-Latest de waarde beta terug. Een versie vastzetten is dan nog niet mogelijk, er wordt altijd de laatste versie geserveerd. Als een bèta endpoint een officiele release krijgt, zal een X-API-Version van voor die release datum, matchen aan deze eerste release.

Op docs.nextpertise.nl komt een pagina die per versie beschrijft welke endpoints een breaking change hebben gehad. Elke versie op die pagina kun je vastzetten. Aan de hand van die documentatie weet je welke aanpassingen je moet doorvoeren om te updaten.

In het eerste kwartaal van 2027 willen we de API uit bèta halen. We wachten hiervoor op de release van de availability API (de zipcode checker). Tot die tijd zijn er nog een aantal breaking changes noodzakelijk. Wij adviseren om de X-API-Version alvast te zetten zodat je direct beschermd bent tegen breaking changes zodra wij de eerste versie publiceren.

Lees meer in de documentatie over API-versiebeheer.