| 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.
...