API Versionering

Algemeen principe

Het uitgangspunt voor de VHP API versioneringsaanpak zijn de richtlijnen zoals gepubliceerd door Digitaal Vlaanderen op: https://data.vlaanderen.be/doc/richtlijnen/iv-rest-api-richtlijnen/

Dit wil zeggen dat:

• de REST URL wordt geformatteerd als { protocol }://{ hostname }/api/{ version }/{ resource}/{ identifier }

• de versie van de API mee is opgenomen in de URL

• een versie wordt genoteerd als kleine letter 'v' met een volgnummer, bijvoorbeeld v1, v2 of v14. Er worden enkel major versies opgenomen.

• Minor en patch changes worden via de beschrijving van het endpoint in de OpenAPI specificatie en op Confluence bekend gemaakt. Deze waarde volgt de semantic versioning regels: v.MAJOR.MINOR.PATCH.

Definitie Major.Minor.Patch

• Major: Dit nummer wordt verhoogd wanneer er incompatibele API wijzigingen (breaking changes) zijn aangebracht. Dit betekent dat de geïntegreerde software van de aansluiters mogelijks niet meer correct zal werken met de nieuwe wijziging.

• Minor: Dit nummer wordt verhoogd wanneer er nieuwe functionaliteit is toegevoegd aan de software, terwijl de bestaande API compatibel blijft. De geïntegreerde software van de aansluiters zal nog steeds werken, maar mist mogelijk wel de nieuwe functies.

• Patch: Dit nummer wordt verhoogd wanneer er bugfixes zijn toegepast in het VHP. Deze wijzigingen zouden geen invloed moeten hebben op de bestaande functionaliteit en compatibiliteit aan de aangesloten software.

Definitie Breaking en Non Breaking Change

In de context van VHP API-ontwikkeling verwijzen de termen "non-breaking change" en "breaking change" naar de impact van wijzigingen in de API op bestaande API-gebruikers.

• Een non-breaking change is een wijziging die geen invloed heeft op de bestaande API-gebruikers en waarvoor zij geen wijzigingen hoeven aan te brengen in hun code of configuratie om de API te blijven gebruiken. Voorbeelden van niet-brekende wijzigingen zijn onder andere

  • het toevoegen van nieuwe endpoints of queryparameters

  • of het wijzigen van het responsformaat van een bestaand eindpunt op een backwards compatible manier door bv een veld hieraan toe te voegen.

• Een breaking change is een wijziging die wel invloed heeft op de bestaande API-gebruikers en waarvoor zij wijzigingen moeten aanbrengen in hun code of configuratie om de API te blijven gebruiken. Onder breaking changes verstaan we zowel structurele als gedragsmatige wijzigingen.

  • Structurele wijzigingen: Deze wijzigen de structuur van de API zelf, zoals het verwijderen van een endpoint of het wijzigen van de invoerparameters van een endpoint.

  • Gedragsmatige wijzigingen: Deze wijzigen hoe de API zich gedraagt, zoals het wijzigen van de logica van een endpoint, het wijzigen van de statuscodes die worden geretourneerd.

Samengevat:

• Non-breaking: Geen impact op aansluiters, geen codewijzigingen nodig.

• Breaking: Impact op aansluiters, codewijzigingen vereist.

  • Structureel: Wijzigingen aan de API-structuur.

  • Gedragsmatig: Wijzigingen aan het API-gedrag.

API’s in ontwikkeling

Voor API's die zich nog in ontwikkeling bevinden, volgen we onderstaande regels:

• De major versie nul (v.0.y.z) duidt aan dat de API nog volop in ontwikkeling is. Alles KAN op elk moment veranderen. De publieke API MAG NIET worden beschouwd als stabiel.

• De minor versie wordt verhoogd bij breaking changes.

• De patch versie wordt verhoogd bij non-breaking changes en bugfixes.

Let op: deze aanpak verschilt met die van de stabiele API’s (major versie ≥ 1), waarbij een verhoging van de minor of patch versie uitsluitend plaatsvindt bij non-breaking changes.

Het gebruik van een API met een major versie 0 geeft aan dat deze zich nog in actieve ontwikkeling bevindt en onderhevig is aan aanzienlijke wijzigingen. Gebruikers moeten zich ervan bewust zijn dat hun code mogelijk verbroken wordt met toekomstige updates.

Wanneer de major versie 0 is kunnen brekende wijzigingen worden aangebracht zonder dat hiervoor een backwards compatibel alternatief wordt voorzien.

Het staat de aansluiters vrij om al dan niet gebruik te maken van een API die nog in ontwikkeling is. Het VHP streeft er wel naar om breaking changes voor API’s die nog in ontwikkeling zijn maximaal op voorhand te bespreken met de aansluiters.

Uitfasering van oudere API versies

Major releases van API's zijn nooit backward compatible. Immers, als een nieuwe release van de API niet tot backward incompatibiliteit leidt, is er geen reden om een major versie omhoog te gaan en spreken we van een minor of patch release. Op het moment dat er een major release plaatsvindt, is het de bedoeling dat alle afnemers deze nieuwe versie implementeren.

In geval van breaking changes verhoogt de major versie en dus ook de REST URL { version }. In kader van operationele backwards compatibility naar API afnemers toe, voorzien we een transitieperiode bij het uitbrengen van een nieuwe REST URL { version }, waarbij de vorige versie gedurende 6 maanden ondersteund blijft na de in productiestelling van de volgende versie.

Stap voor stap betekent dit het volgende:

1. Communicatie opkomende nieuwe endpoint versie naar aansluiters om feedback en deprecation periode te capteren

2. Release nieuwe endpoint versie

3. Bepalen deprecation datum door het VHP team (6 maanden na in productie stelling volgende versie)

4. De API-documentatie van de oude endpoint wordt aangevuld met volgende velden:

   1. deprecated: true: geeft aan dat de endpoint deprecated is

   2. x-deprecated-since: RX: vanaf welke release de endpoint deprecated is geworden

   3. x-supported-until: RY: vanaf welke release de endpoint niet meer ondersteund zal worden

5. Aansluiters worden via e-mail of een ander communicatiekanaal op de hoogte gebracht

6. Via rapportering het gebruik van de oude versie in alle omgevingen monitoren gedurende de deprecation periode

7. Endpoint oude versie, inclusief documentatie, verwijderen op geplande datum en feedback monitoren

Voorbeeld: er is een major release voor POST /aansluiter/v1/stukken in R20

1. Communicatie nieuwe POST /aansluiter/v2/stukken via e-mail en IT-overleg

2. POST /aansluiter/v2/stukken wordt aangemaakt in R20

3. Er wordt bepaald dat vanaf R34 POST /aansluiter/v1/stukken niet meer gebruikt kan worden

4. De API-documentatie van POST /aansluiter/v1/stukken wordt aangevuld met volgende velden:

   1. deprecated: true

   2. x-deprecated-since: R20

   3. x-supported-until: R34

5. Dit wordt gecommuniceerd via e-mail en het IT-overleg

6. Maandelijkse opvolging om na te kijken of de oude versie nog gebruikt wordt

7. Bij R34 wordt de oude endpoint versie verwijderd. In de flightchecks voor R34 komt te staan dat de documentatie ook verwijderd mag worden.

VHP streeft ernaar om het aantal breaking changes maximaal te beperken. Aansluiters kunnen op het IT overleg feedback geven op de besproken breaking changes.