Versiebeheer

Owned by Koen
Last updated: Apr 18, 2024
2 min read

Titel

Versiebeheer

Status

In ontwikkeling ROSA-Architectuurscan BEsluitvorming in beheer

Versie

0.0.5

Datum

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