Voeg regel toe over het documenteren van server URLs

[TimvdLippe]

Hiermee maken we een eerste stap in het enforceren
van informatie over servers. Tevens maken we hiermee
duidelijk dat een relatieve URL is toegestaan, echter
moet er altijd minstens 1 absolute URL zijn.

Part of #208
Fixes #290

[github-actions]

Preview link voor pull request
Diff met W3CDiff

[joostfarla]

Is deze uitzondering echt nodig? Zou het niet beter zijn om altijd absolute URLs te vereisen?

[TimvdLippe]

Dat is het voorstel in #290, zie dat issue voor meer context.

[dvh]

Dit blijft een ingewikkelde discussie. Als je ervan uitgaat dat een OAS op endpoint/openapi.json draait, dan zou 1 OAS eigenlijk überhaupt nooit meerdere servers kunnen hebben:

prod:

• url: api.developer.overheid.nl/v1
• oas: api.developer.overheid.nl/v1/openapi.json

test:

• url: api.test.developer.overheid.nl/v1
• oas: api.test.developer.overheid.nl/v1/openapi.json

Wat ik heel wenselijk zou vinden zou de classificatie van een omgeving zijn, zodat je weet welke server bij prod, test, dev, etc. hoort (ook tbv het API register). Maar die optie heeft OAS niet, dus dan zouden we iets af moeten spreken over de volgorde, naam of een extensie, zoals beschreven in #208. Mogelijk maakt het deze discussie makkelijker als we daar iets voor verzonnen hebben?

[TimvdLippe]

Ik heb Spectral regels kunnen schrijven en gecheckt of er API's wel/niet aan voldoen. Met deze regels (dus max 1 relative URL), voldoet er 1 API niet: het API register van developer.overheid.nl (waarschijnlijk vergeten te updaten?)

Als we helemaal geen relatieve URLs toestaan, dan zijn dit de statistieken:

Statistics for rule nlgov:servers-no-relative:

Analyzed: 179
Passing: 161
Percentage: 89%

Voorbeelden:

• Verzoekconfiguratie-Beheren
• Omgevingsdocumenten Verbeelden

Het lijken vooral DSO API's te zijn die dit patroon volgen