| Table of Contents | ||
|---|---|---|
|
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/
...
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.
...
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:
...
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 na aankondiging op het IT overleg ondersteund blijft na de in productiestelling van de volgende versie.
Stap voor stap betekent dit het volgende:
Communicatie opkomende nieuwe endpoint versie naar aansluiters om feedback en deprecation periode te capteren
Release nieuwe endpoint versie
Bepalen deprecation datum door het VHP team (6 maanden na aankondiging op IT overlegin productie stelling volgende versie)
De API-documentatie van de oude endpoint wordt aangevuld met volgende velden:
deprecated: true: geeft aan dat de endpoint deprecated isx-deprecated-since: RX: vanaf welke release de endpoint deprecated is gewordenx-supported-until: RY: vanaf welke release de endpoint niet meer ondersteund zal worden
Aansluiters worden via e-mail of een ander communicatiekanaal op de hoogte gebracht
Via rapportering het gebruik van de oude versie in alle omgevingen monitoren gedurende de deprecation periode
Endpoint oude versie, inclusief documentatie, verwijderen op geplande datum en feedback monitoren
...