Vaste URL voor serveren OAS-schema

[HenriKorver]

Het zou mooi zijn als we een gemeenschappelijke afspraak kunnen maken over op welke URL het OAS-schema geserveerd wordt (faciliteert self-discovering clients). Bijvoorbeeld in dit vaste formaat:

https://.../.../api//schema/openapi.yaml

Voor het opvragen van het schema van onze API voor de zaakregistratiecomponent (zrc) ziet de URL er zo uit: https://ref.tst.vng.cloud/zrc/api/v1/schema/openapi.yaml

[dvh]

Wij serveren hem nu direct op het endpoint, bijv: https://data.informatiehuisruimte.nl/api/ruimtelijke-plannen/v1/. Met /schema 'bezet' je het path voor mogelijke collectie's die 'schema' heten, daarom zou ik in dit geval adviseren een naming convention op te nemen zoals we bijvoorbeeld bij de 'niet-REST-endpoints' als /_zoek doen: /_schema/. Dan heb je nog de vraag welke locatie dit moet zijn en of dit yaml of json is (of content-negotiation ondersteunt en dan is de vraag wat de default is). Ik kan het issue niet meer vinden, maar weet wel dat er ook al eens geopperd is om https://tools.ietf.org/html/rfc5785 te gebruiken om een /.well-known/oas path op te nemen. Dit is overigens niet opgepikt door de OAS werkgroep omdat zij zich enkel willen beperken tot de inhoud van de spec zelf.

Machines consumeren met name JSON en als er YAML wordt aangeboden wordt dit eerst vertaald naar JSON. In dat opzicht lijkt standaard JSON serveren een juiste keuze die nu door DSO is gemaakt (en waar onze API's nog niet aan voldoen overigens ;-)). YAML gebruiken we in het werkbestand waar mensen mee moeten werken.

Zie ook: OAI/OpenAPI-Specification#1110

[joeribekker]

Er is wel (deels) een RECOMMENDED manier:

It is RECOMMENDED that the root OpenAPI document be named: openapi.json or openapi.yaml.

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#document-structure

Dit geeft in ieder geval aan dat er een URL moet komen eindigend op "openapi.yaml". De vraag resteert dan waar deze file moet leven.

Het endpoint waar @dvh op serveert (https://data.informatiehuisruimte.nl/api/ruimtelijke-plannen/v1/) is meer geschikt voor een JSON-response met daarin alle beschikbare endpoints. Als deze URL in plaats daarvan: https://data.informatiehuisruimte.nl/api/ruimtelijke-plannen/v1/openapi.yaml wordt, hanteren we de richtlijn van OAS3 en we reserveren geen mogelijk pad. 🌈

[dvh]

It is RECOMMENDED that the root OpenAPI document be named: openapi.json or openapi.yaml.

Dit gaat over het root document, dus het bestand zelf in het geval er references zijn naar onderliggende/externe bestanden. Neemt overigens niet weg dat ik het wel chique vind om jouw voorstel te volgen.

Omdat dit endpoint met name voor machines is stel ik wel voor om in ieder geval een openapi.json te serveren zodat de conversie niet in de tools zelf hoeft te gebeuren.

[jasperroes]

API-51 principe aanpassen: voorstel is met _schema, URL's worden dan bijvoorbeeld: https://data.informatiehuisruimte.nl/api/ruimtelijke-plannen/v2/_schema/openapi.yaml
https://data.informatiehuisruimte.nl/api/ruimtelijke-plannen/v2/_schema/openapi.json

Verplicht om iig .json aan te bieden, optioneel ook als .yaml

[PieterHering]

Kijk ook naar de formulering van regel API-52 en overweeg om die te splitsen (zie hieronder)
In de beschrijving van de regel geen onderbouwing waarom JSON gebruikt moet worden. Voor eventuele aanpassing op een later moment kan zo'n onderbouwing handig zijn.

Voorstel voor verbetering
API 51-1 - OAS beschikbaar via specifieke URI op ROOT endpoint
API 51-2 - OAS beschikbaar minimaal in JSON formaat

[jasperroes]

Kreeg nog additionele input: waarom op /_schema en niet op /_spec. Het gaat namelijk om de Open API Specificatie en niet om een schema.

[joostfarla]

Waarom dan niet gewoon:
https://data.informatiehuisruimte.nl/api/ruimtelijke-plannen/v2/openapi.yaml
https://data.informatiehuisruimte.nl/api/ruimtelijke-plannen/v2/openapi.json
Het risico dat een resource-naam hiermee wordt "bezet" is hierbij geen issue.

[HenriKorver]

Eens met @joostfarla. Ditzelfde voorstel is al eerder gedaan door @joeribekker (zie deze post ).

[fsamwel]

Is het ook mogelijk dat we als extensie op de problem+json response een link opnemen naar de API-specificaties (yaml en/of json)?
Dan maakt het namelijk niet meer uit waar de OAS staat en hoeft de gebruiker ook niet te weten waar die staat. Wanneer iemand een foute request doet (zeker in de 4xx serie) kan je aannemen dat de gebruiker wel eens geïnteresseerd zou kunnen zijn in de API definitie en is het dus wel zo vriendelijk de uri daarvan te leveren.

Daarbij speelt dat soms de provider (ik ken in ieder geval één landelijke voorziening waarvoor dit geldt) de operapi.yaml niet eenvoudig op het endpoint van de API kan leveren. Deze hoeft hiervoor dan geen extra maatregelen te nemen.

Bijvoorbeeld:
{
"detail": "Geen adres gevonden met de opgegeven nummeraanduiding identificatie.",
"status": 404,
"title": "Opgevraagde resource bestaat niet.",
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
"instance": "https://api.test.kadaster.nl/vhc/adressen/0599200000193766"
"specs": "https://github.com/VNG-Realisatie/Haal-Centraal-BAG-bevragen/blob/master/api-specificatie/resolved/openapi.yaml"
}

[joostfarla]

@fsamwel: Het serveren van de OpenAPI specificatie heeft niet alleen betrekking op foutafhandeling, maar is voornamelijk een standaard conventie om de spec als vertrekpunt te kunnen nemen bij het discoveren van de API. Zo weten ook externe partijen eenvoudig de spec te vinden en kunnen zij er eventueel naar verwijzen als "permanent link".

Ik ben overigens wel benieuwd naar de technische beperkingen waarom sommige partijen dit niet zouden kunnen. Mogelijk kunnen we daarin suggesties doen, of mogelijk kan dit aanleiding zijn voor een alternatief voorstel.