Versiebeheer

Titel

Versiebeheer

Status

DRAFT ARCHITECTenraad REDACTIE BEsluitvorming CONCEPT

Stadium

POC PILOT BEHEER

Versie

0.0.2

Datum

21 April 2023

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:

  • Voor het bepalen van versienummers worden de principes van de Nederlandse API Strategie IIa gehanteerd.

  • Iedere API krijgt zijn eigen versienummer. Dit versienummer wordt toegevoegd aan alle dataobjecten uit de API in het veld schemaVersion.

  • Het veld schemaVersion is verplicht in ieder bericht en in iedere response.

  • Voor iedere API is het mogelijk om in een query parameter of de body de parameter schemaVersion toe te voegen. De response wordt vervolgens gegeven in de aangevraagde versie.

  • Voor een Verzender is het handig om te kunnen bepalen welke versienummers en APIs een Ontvanger ondersteunt in de Events API. Dit kan de Verzender opvragen via het endpoint GET Versions in de Events API.

  • De stelregel in Edu-V is dat partijen 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 partijen om tijdig, maar ook op een moment dat voor de partij 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 partijen 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.