Comments (10)
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. 🌈
from kp-apis.
Kreeg nog additionele input: waarom op /_schema en niet op /_spec. Het gaat namelijk om de Open API Specificatie en niet om een schema.
from kp-apis.
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.
from kp-apis.
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
from kp-apis.
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.
from kp-apis.
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
from kp-apis.
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
from kp-apis.
Eens met @joostfarla. Ditzelfde voorstel is al eerder gedaan door @joeribekker (zie deze post ).
from kp-apis.
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"
}
from kp-apis.
@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.
from kp-apis.
Related Issues (20)
- GEO-API-11: PUT/PATCH toevoegen HOT 1
- Voorbeelden in Nederlands of Engels
- Beschrijven wanneer een module normatief of niet normatief genoemd wordt
- Broken link in reference to centrumvoorstandaarden HOT 1
- Redactie, o.a. issues hernummeren HOT 3
- Probleem met bboxCRS HOT 1
- Openstaande punten geo module HOT 1
- laatste controle op versie ter vaststelling geomodule 14 april HOT 3
- Event Driven Architecture / Notificaties HOT 1
- Voorschrijven ontsluiten landingspagina zonder autorisatie
- Paginering in JSON HOT 1
- Redactioneel commentaar op API designrules 2.0 HOT 1
- Spelling incorrect in titel HOT 1
- Link incorrect in Access Control HOT 2
- Richtlijnen voor het bijwerken van (meervoudige) geneste gegevens HOT 2
- huidige waarde <epsg:CommonMetadata> element nog correct? HOT 3
- Standaardiseren API Lifecycle Management HOT 2
- v1.1 module transport security opnemen in ADR 2.1
- In ADR 2.0 is uitzondering voor toestaan trailing / op landing page verdwenen HOT 1
- Notificaties: Cloudevents AsyncAPI en transportprotocollen HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from kp-apis.