Versiebeheer

Titel	Versiebeheer
Status	In ontwikkeling ROSA-Architectuurscan BEsluitvorming in beheer
Versie	1.0.0
Datum	27 Mei 2024
Auteur	Architectenraad Edu-V
Acties	Geen openstaande acties

De koppelvlakspecificatie van Edu-V zal in de toekomst verder doorontwikkeld worden. Vanuit dit perspectief is het wenselijk om afspraken te maken over ondersteuning van versies en versiebeheer.

Dit is als volgt ingericht:

Iedere API krijgt zijn eigen versienummer.
Voor het bepalen van versienummers worden de principes van de Nederlandse API Strategie IIa gehanteerd.
- Het formaat van het versienummer is major.minor.patch.
- Het major nummer staat in de URI van de API url.
  - Bijvoorbeeld: https://api.example.org/v1/
- Het volledige versienummer is opgenomen in de Response Header.
  - Bijvoorbeeld: API-Version: 1.0.2
De stelregel in Edu-V is dat leveranciers tenminste de vorige versie (t-1) en binnen redelijke termijn de meest actuele (t) van de API ondersteunen. Alle versies ervoor (t-2 en eerder) worden niet ondersteund.
- Dit maakt het mogelijk voor leveranciers om tijdig, maar ook op een moment dat voor de leverancier past, de wijziging te implementeren.
- Indien de wijziging kritisch is voor het correct functioneren van Edu-V, dan kan van deze stelregel worden afgeweken. In dat geval wordt aan alle leveranciers gevraagd om tenminste ook de meest actuele versie te ondersteunen.

Release notes

Deze uitwerking is gebaseerd op basis van de volgende stappen:

0.0.1: De documentatie is overgenomen vanuit het SEM Ecosysteem. De terminologie is in lijn gebracht met de gegevensdefinities van Edu-V.
0.0.2: Tijdens de werkconferentie van de Architectenraad Edu-V van 18 april 2023 is aangegeven dat voor versiebeheer er een richtlijn is vanuit de Nederlandse API strategie. Dit is aangepast op deze pagina.
0.0.3: Tekst aangepast conform wijzigingen in transactierollen.
0.0.4: De pagina is besproken tijdens de bijeenkomst van de Architectenraad Edu-V en is gereed voor de ROSA-architectuurscan.
0.0.5: Het hanteren van versienummers is aangepast conform de Nederlandse API strategie. Dit heeft ook geleid tot wijzigingen in alle APIs:
- Het attribuut schemaVersion is uit de berichtspecificaties gehaald.
- De query parameter schemaVersion is uit de koppelvlakspecificatie gehaald.
- Voor de volledigheid is iedere API pagina op Confluence voorzien van een versienummer voor de documentatie en de schemaVersion van de API.
1.0.0: Het Architectuurkader Edu-V is vastgesteld als startpunt voor de implementatie. Tevens is instemming verleend op verdere doorontwikkeling van het Architectuurkader Edu-V op basis van de Architectuurprincipes. Dit akkoord is verleend op het Bestuurlijk Overleg van 27 mei 2024.