Sta relatieve Server API URL toe.

[kad-sprenr]

De huidige regex dwingt af dat alle server urls beginnen met https maar, dwingen daarmee impliciet ook af dat alle server urls absolute paden zijn (d.w.z. inclusief schema + hostname). Ik definieer zelf in alle API specificaties een aantal absolute URLs maar ook altijd één relatieve. Dit is met name handig voor API's die op heel veel verschillende hosts beschikbaar gesteld worden, wat heel normaal is in complexe OTAP-straten of in ontwikkelomgevingen met een hoge mate van virtualisatie.

Is het de bedoeling dat relatieve server URLs afgekeurd worden door servers-use-https, of is dit een onbedoeld bijeffect?

[kad-sprenr]

Zie #291

[TimvdLippe]

Naar mijn weten geen bewuste keuze om relatieve paden wel/niet te accepteren. PR #291 veranderd enkel de linter configuratie. Ik denk dat we eerst met de TO-leden een inhoudelijke discussie en beslissing moeten maken of relatieve URLs toegestaan zijn of niet.

Ik denk dat we hiervoor een nieuwe regel moeten schrijven in het hoofdstuk "Documentation". @kad-sprenr heb je een voorstel hoe we hier om mee moeten gaan? Denk hierbij aan de volgende zaken:

1. Is een combinatie van absolute en relatieve URLs toegestaan?
2. Tegen welke base URL moet de relatieve URL worden geresolvet?
3. Moeten we een base URL enforceren? Ergo moeten we enforceren dat als er een relatieve URL in staat, dat $self spec ingevuld is?
4. Hoe relateert dit tot /core/publish-openapi? Sommige organisaties voldoen niet aan deze regel, dus moet de relatieve URL dan nog wel geresolvet worden als die mogelijk in tegenspraak is met de locaties in de servers array

[kad-sprenr]

Is een combinatie van absolute en relatieve URLs toegestaan?

Wat mij betreft wenselijk, bijvoorbeeld een absolute url naar een productie-endpoint en daarnaast een relatieve url ten bate van alle andere endpoints.

Tegen welke base URL moet de relatieve URL worden geresolvet?
Moeten we een base URL enforceren? Ergo moeten we enforceren dat als er een relatieve URL in staat, dat $self spec ingevuld is?

Ik zou daar de logica volgen die ook beschreven wordt in OAS (https://spec.openapis.org/oas/v3.2.0.html#establishing-the-base-uri):

• wanneer de server URL absoluut is, resolve die URL
• wanneer de server URL relatief is, en $self absoluut, combineer met $self
• wanneer beide relatief zijn of $self ontbreekt, combineer met de retrieval URI (d.w.z. die van de plek waar de spec gehost wordt)
  Dit laatste is heel prettig als je als developer zelf ReSpec of Swagger host naast je spec.

Hoe relateert dit tot /core/publish-openapi? Sommige organisaties voldoen niet aan deze regel, dus moet de relatieve URL dan nog wel geresolvet worden als die mogelijk in tegenspraak is met de locaties in de servers array

Ik snap het woord 'tegenspraak' hier niet helemaal. API's kunnen prima tegelijkertijd op meerdere server URLs gehost worden. Wat ik wel een goed idee vind, is dat als je je eigen spec (en/of ReSpec/Swagger) ergens host, en je hebt een relatieve server URL, dat dat dan in context met elkaar klopt (zoals hierboven beschreven).

Hier een voorbeeld van een spec: https://service.omgevingswet.overheid.nl/publiek/omgevingsdocumenten/api/geometrieopvragen/v1/openapi.json

Hierbij is de eerste server URL de relatieve URL die in de context van deze specifieke retrieval begrepen kan worden, en de andere twee server URLs zijn absoluut, en geven ook informatie voor gebruikers die deze spec ergens anders aantreffen dan op de host.

[TimvdLippe]

Ik zou daar de logica volgen die ook beschreven wordt in OAS

Ik begrijp de resolution logica, maar mijn vraag was meer of het wenselijk is om deze logica te volgen. Bij de design rules kijken we naar wat wenselijk is. Dus je kan daar bepalen "relatief mag, maar $self MOET ingevuld zijn". Dat voorkomt bullet point 3 en is dus een keuze of je dat wilt doen of niet. Mijn vraag is dus: is het wenselijk dat bullet point 3 ondersteund wordt of niet?

Ik snap het woord 'tegenspraak' hier niet helemaal

Mijn vorige punt is in het verlengde hiervan. Wat we zien is dat overheidsorganisaties niet voldoen aan de /core/publish-openapi regel. Dat betekent dat een api die op https://example.com/api/v1 draait, dat de openapi.json op https://developers.example.com/portal/onze-mooie-api/openapi.json staat. Hierbij staat in de servers mogelijk wel https://example.com/api/v1 maar ook dat is niet altijd het geval.

In het scenario dat de specificatie op https://developers.example.com/portal/onze-mooie-api/openapi.json staat en de daadwerkelijke API dus op een ander pad, is het dan oke om de relatieve URL toe te staan? En moet die URL dan resolven op basis van https://example.com/api/v1 (waar de openapi.json eigenlijk had moeten staan) of https://developers.example.com/portal/onze-mooie-api/ ?

In de voorbeeld spec die je linkt voldoe je aan /core/publish-openapi. Namelijk dat https://service.omgevingswet.overheid.nl/publiek/omgevingsdocumenten/api/geometrieopvragen/v1/ de base URL is en als je er openapi.json achter plakt, dat je dan inderdaad op die correcte plek komt te staan. En met de relatieve URL voldoe je ook, want als je /publiek/omgevingsdocumenten/api/geometrieopvragen/v1 resolvet ten op zichte van de locatie van de openapi.json, dan kom je ook weer op de absolute locatie uit.

Concreet scenario:

1. API voldoet niet aan /core/publish-openapi
2. Het publiceert de openapi.json op https://example.com/portal/onze-mooie-api/openapi.json (dus zonder developers.example.com)
3. Het zet in de servers een relatieve URL /api/v1

Voldoet deze API dan wel of niet aan de "te bedenken" design rule?

[kad-sprenr]

Ik denk dat de relatieve server URL met name nuttig is voor 'intern' gebruik - d.w.z. voor de developer experience van de aanbieder, zodat die de API op willekeurige plekken kan serveren en daar ook een nette Swagger/ReSpec heeft voor test/ontwikkel/demo-doeleinden. Richting de externe gebruiker wil je juist duidelijk zijn en één of meerdere absolute URLs definiëren (met het oog op de 'Findable' in de FAIR-principes). Ik wil dus eigenlijk voorstellen dat je alleen een relatieve server URL mag aanbieden als je daarnaast ook een absolute server URL aanbiedt. Dat kan wat mij betreft prima onderdeel zijn van de nieuwe design rule.

Ingaand op je scenario: ik denk dat het aanbieden van een relatieve server URL alleen betekenisvol is als je ook voldoet aan /core/publish-openapi, omdat je anders niet in de juiste context zit om betekenisvol de resources in de spec te resolven.

Kort samenvattend mijn mening: je mag relatieve server URL definieren, maar alleen als je ook ten minste één absolute server URL definieert en voldoet aan /core/publish-openapi.

[TimvdLippe]

Dank voor de suggestie. Ik heb die uitgewerkt in #294 en ter review voorgelegd aan andere experts. Kun je deze PR ook reviewen of dit de lading dekt wat jou betreft?

[kad-sprenr]

Gereviewd, prima zo wat mij betreft.