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