Versionering nl-test-admin consumerobjecten

[rrutte]

De reguliere OOAPI versionering is momenteel V4 -> V5. Binnen de nl-test-admin consumers hebben we echter onze eigen versionering (0.9.2 0.9.3 0.9.4 etc). Hoe maken we die versionering expliciet?

Simpelste, binnen consumer object versienr attribuut: "consumer_version": "0.9.3". Bij een PUT of PATCH krijg je dat automatisch mee obv de aanleverende partij.

Kan je bij een GET ook om een specifieke consumer versie vragen?

[hamrt]

Voor nu gekozen als richting om met de HEADER door te geven welke versie van de consumer wordt gebruikt. Aanvullend Er wordt GEEN consumer informatie verstrekt als er niet expliciet om wordt gevraagd.

[hamrt]

@hamrt nog doorzetten richting OOAPI werkgroep

[hamrt]

Door te voeren voor 0.9.4 als voorbeeld ook meenemen

[hamrt]

Doorzetten naar de technische werkgroep voor OOAPI

[hamrt]

Ook in documentatie en voorbeelden opnemen hoe we met consumer objecten omgaan (waar het wel en niet verplicht is in URL / header)

[remco-jak]

Donderdag 25 april 2024 stond dit onderwerp op de agenda van de Technische OOAPI werkgroep.

Namens MBO OKE heb ik daar een voorstel gedaan. Dit onderwerp heb ik van te voren met aan een aantal trouwe ooapi technische werkgroep leden besproken, en hun inzichten heb ik proberen mee te nemen in het voorstel.

voorstel

Doel: komen tot een eenduidige afspraak die werkt voor alle consumers

uitgangspunten:

1. MBO OKE werkgroep heeft de voorkeur om consumer versie met behulp van een header te communiceren
2. zowel ooapi als consumer versie moet gecommuniceerd kunnen worden in 1 request / response
3. het aantal consumers waarvoor versie nummers wordt gecommuniceerd is gelimiteerd tot 1 per request / response
4. we willen dicht bij bestaande web standaarden blijven
5. oplossing moet simpel, duurzaam en eenduidig zijn

Mijn voorstel is om Accept en Content-Type headers te gebruiken om versies te communiceren. Dit is een gestandaardiseerd mechanisme, en heeft als voordeel dat gebruik gemaakt kan worden van content negotiation, een bestaande en beschreven afspraak over het communiceren van ondersteunde en geprefereerde data types / representaties / versies.

In Accept en Content-Type headers zijn mime-types opgenomen om het type data te beschrijven waar het over gaat. Er is een pre-fix vnd (vendor) beschikbaar voor organisatie specifieke mime-types. Bij ooapi data zou dat kunnen zijn: application/vnd.ooapi

In Accept en Content-Type headers kan voor elke mime-type parameters worden toegevoegd. De parameter version is veel gebruikt. Voor de consumer zou een consumer-version parameter kunnen worden toegevoegd.

OOAPI versie

format voor gebruik in een header, inclusief versie
application/vnd.[organization/data-type]+[representation];version=x

application/vnd.ooapi+json;version=5.*

OOAPI en consumer versies

format voor gebruik in een header, inclusief ooapi en consumer versie
application/vnd.[organization/data-type]+[representation];version=x;consumer-version=x

application/vnd.ooapi+json;version=5.*;consumer-version=0.9.4

voorbeelden

Header bij een GET request, waarbij de versturende partij ooapi v5, en consumer versies 0.9.3 én 0.9.4 ondersteund:

Accept: application/vnd.ooapi+json;version=5.*;consumer-version=0.9.3, application/vnd.ooapi+json;version=5.*;consumer-version=0.9.4

Het response, of bij een POST, PUT of PATCH request:

Content-Type: application/vnd.ooapi+json;version=5.*;consumer-version=0.9.4

N.B.
De communicatie over de consumer-naam is geen onderdeel van dit voorstel. Hiervoor moeten de al in gebruik zijnde afspraken binnen de projecten gebruikt worden.
Aan Accept header mime types kan een q parameter worden toegevoegd voor weging, zoals gebruikelijk is, en volgens web standaarden.
Voor meer info zie ook RFC 2616 (IETF, Internet Engineering Task Force)

uitkomst ooapi werkgroep overleg

De wens voor het gebruik van Accept en Content-Type headers hiervoor wordt begrepen, en de ooapi werkgroep kan meegaan in die richting.

Voor een gedetailleerde uitwerking vanuit de ooapi werkgroep is meer tijd nodig. Het zou goed zijn om een voorstel vanuit MBO OKE toe te voegen aan de issue lijst open-education-api specification

[remco-jak]

discussiepunt 1

Het voorstel vermeldt:
De communicatie over de consumer-naam is geen onderdeel van dit voorstel. Hiervoor moeten de al in gebruik zijnde afspraken binnen de projecten gebruikt worden.

er zijn twijfels of elk systeem hier nu goed mee kan omgaan. Het kan zijn dat de consumer naam waar het om gaat pas duidelijk wordt tijdens het inspecteren van de inhoud van de data, mogelijk is de inhoud van de header dan niet meer (eenvoudig) beschikbaar.

Totdat de OOAPI specificatie het consumer mechanisme strakker beschrijft, waarbij duidelijke afspraken zijn gemaakt over het communiceren in welke context/consumer uitwisseling van data plaatsvindt, zou daar binnen MBO OKE een afspraak over gemaakt kunnen worden.

optie 1

De consumer naam kan opgenomen worden in de waarde van de consumer-version
Bijvoorbeeld:

application/vnd.ooapi+json;version=5.*;consumer-version=nl-test-admin-0.9.4

optie 2

bij elk request kan een GET param ?consumer=nl-test-admin in de url opgenomen worden ( ook in de post/put/patch requests)

discussiepunt 2

Wat wordt er teruggestuurd als er geen duidlijkheid is over de gewenste versie?

Met een q parameter kan worden aangegeven welke versie het lieftst ontvangen wordt. Als die weging ontbreekt, zou het hoogste versie nummer de voorkeur moeten hebben.

Als er geen versienummer wordt genoemd in de Accept header zou het hoogste versienummer dat beschikbaar is moeten worden teruggestuurd.

Voorbeelden van requests en de responses naar een server die zowel versie 0.9.3 als 0.9.4 ondersteund: (volgens "de web standaard")

GET request
Accept: application/vnd.ooapi+json;version=5.*;consumer-version=0.9.3, application/vnd.ooapi+json;version=5.*;consumer-version=0.9.4

Response: versie 0.9.4

GET request met weging:
Accept: application/vnd.ooapi+json;version=5.*;consumer-version=0.9.3;q=0.9, application/vnd.ooapi+json;version=5.*;consumer-version=0.9.4;q=0.8

Response: versie 0.9.3

GET request met te oude versie én wildcard
Accept: application/vnd.ooapi+json;version=5.*;consumer-version=0.7, */*

Response: versie 0.9.4 (nieuwste versie, volgens OKE afspraak)

GET request met niet-ondersteunde versie:
Accept: application/vnd.ooapi+json;version=5.*;consumer-version=1.0.0

Response: status code 501 (Not Implemented)

[hamrt]

Deze moet vanuit OOAPI werkgroep doorgezet worden in een breder geheel. Vraag is namelijk wat de gevolgen zijn wanneer we dit bredr uit zouden zetten voor de andere endpoints e.g eduxchange