OpenAPI Specification

Deze gegevens zijn afkomstig van https://www.forumstandaardisatie.nl/open-standaarden/Openapi-specification

Uitleg: Koppeling standaarden van Forum Standaardisatie

07-12-2022: wij toetsen of de standaard OAS in de nieuwe versie (3.1) geschikt is om te blijven verplichten aan de overheid (‘pas toe of leg uit’-verplichting). De procedure is tijdelijk stilgelegd vanwege een aantal geconstateerde aandachtspunten

Beschrijving
Voor zowel mensen als computers is het fijn als de documentatie van een API makkelijk te lezen is. In een OpenAPI Specification staan de eigenschappen van de data die een API als input accepteert en als output teruggeeft. De overheid en de publieke sector beschrijven deze specificaties volgens een vaste werkwijze. Zo wordt de documentatie voorspelbaar en de API's makkelijker te (her)gebruiken.
Status
Lijst status	Verplicht (pas toe leg uit)
Functioneel toepassingsgebied	OAS moet worden toegepast op het beschrijven/specificeren van een REST API.
Organisatorisch werkingsgebied	Nederlandse overheden (Rijk, provincies, gemeenten en waterschappen) en instellingen uit de (semi-) publieke sector.
Aanvullende verplichtingen
Europese status (MSP)	Nee
Nut en werking
Typering
Nut	Een API is in de praktijk zo effectief als z'n documentatie. De documentatie van een API moet voor machines leesbaar en voor mensen begrijpelijk zijn. OAS 3.0 geeft ontwikkelaars van applicaties een eenduidige en leesbare beschrijving van een REST API waarmee zij de API kunnen gebruiken zonder te hoeven weten hoe deze geïmplementeerd is. OAS 3.0 zorgt voor gemakkelijker (her)gebruik van APIs en minder leveranciersafhankelijkheid.
Werking	Een OpenAPI Specification (OAS) beschrijft de eigenschappen van de data die een API als input accepteert en als output teruggeeft. OAS 3.0 specificeert alleen welke attributen de API verwerkt en hun datatypen, niet welke implementatie er achter de API schuilgaat. OAS 3.0 is dus een beschrijvende taal en heeft geen binding met specifieke programmeertalen. Een specificatie conform OAS 3.0 is een tekstbestand met een gestandaardiseerde YAML of JSON structuur. Daardoor is OAS zowel leesbaar voor machines als begrijpelijk voor mensen. Met OAS 3.0 kunnen zowel mensen als machines de dataset attributen van een REST API vinden, bekijken en verwerken zonder toegang tot de programmatuur en zonder aanvullende documentatie. OAS 3.0 is zowel compatibel met de voorgaande versie OAS 2.0 als met de alternatieve standaard RAML (RESTful API Modeling Language) die ook veel gebruikt werd.
Relatie met andere standaarden	OAuth SAML
Domein	Uitwisselingsfundament
Trefwoorden	Ruimtelijke ordening, Basisregistraties, Bodem, Geo-informatie
Gangbaar
Detailinformatie
Volledige naam	OpenAPI Specification
Versie	3
Specificatiedocument	https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md
Beheerorganisatie	OpenAPI Initiative
Community	De aanmelding van de standaard wordt ondersteund door Rijkswaterstaat, Geonovum en in ieder geval toegepast door het Kadaster voor haar REST API's. Het Deelprogramma Digitaal Stelsel Omgevingswet gebruikt OAS 2.0 en OAS 3.0.De beheerorganisatie OpenAPI Community is een open community opgezet door de Linux Foundation waarbij het beheer en de ontwikkeling gebaseerd is op een open online dialoog met een community van gebruikers die via een kiessysteem kunnen meebepalen over de prioritering van issues.
Hulpmiddelen	Om bestaande API specificaties om te zetten naar OAS3 zijn er verschillende converters die dit kunnen doen, hieronder enkele voorbeelden: https://apimatic.io/transformer https://mermade.org.uk/openapi-converter< https://mulesoft.github.io/oas-raml-converter/ Ook is het mogelijk om het handmatig te doen, of na het omzetten alsnog handmatig te optimaliseren, zodat je bepaalde zaken die vaker terugkomen (bijv. een ‘id’ parameter) maar op één plek hoeft te specificeren en van daaruit kan hergebruiken. Dat scheelt aanzienlijk in het onderhoud. Bovendien kun je dan ook externe verwijzingen toevoegen en dezelfde zaken hergebruiken over meerdere APIs. Daarnaast zijn er ook verschillende portals die op basis van OAS3 de bij behorende API documentatie kunnen leveren, dat kan bijvoorbeeld via: https://apimatic.io/developer-experience-portal https://stoplight.io/ https://swagger.io/tools/swagger-ui/ https://redocly.github.io/redoc/ Mocht je OAS bestanden willen creëren dan zijn er ook verschillende tools die hierbij kunnen helpen, dit kan bijvoorbeeld via: Verder is het verschillende en documentatie en tooling voor het gebruik van de standaard te vinden en openbaar toegankelijk. Zie bijvoorbeeld: https://github.com/OAI/OpenAPI-Specification of op de website van de beheerorganisatie https://www.openapis.org/ http://spec.openapis.org/oas/v3.0.2 https://www.apicur.io/ http://editor.swagger.io/
Conformiteitstest
Praktijkvoorbeelden
Toetsingsinformatie
Toelichting bij opname	Het Forum Standaardisatie heeft besloten, op basis van de expertbijeenkomst van 5 april 2023, om de toetsingsprocedure tijdelijk stil te leggen. De procedure wordt voortgezet zodra er voldoende voortgang is op de geconstateerde aandachtspunten. Deze aandachtspunten zijn: OAS 3.1 bevat breaking changes ten opzichte van OAS 3.0. OAS 3.1 is niet backward compatible met OAS 3.0; er is onvoldoende (internationale) ondersteunende tooling beschikbaar om OAS 3.1 te implementeren en de transitie van OAS 3.0 naar OAS 3.1 soepel te laten verlopen; op basis van bovenstaande twee redenen zijn de kosten voor de migratie van OAS 3.0 naar OAS 3.1 op dit moment nog te hoog; er is internationaal nog weinig adoptie van OAS 3.1. Dit lijkt de ontwikkeling van goede ondersteunende tools tegen te werken.
Adoptieadviezen
Uitstekend beheer	Nee
Documentatie
Datum van aanmelding	2017-04-24
Datum van besluit	2018-05-25
Overig
Waarvoor geldt de verplichting	OAS moet worden toegepast op het beschrijven/specificeren van een REST API.
Toelichting
Aandachtspunten
Advies aan beheerder
Sjabloon-bestektekst
CPV-code(s)
Leveranciers

Bijlagen:

Copyright: Door Forum Standaardisatie vrijgegeven onder Creative Commons zero

OpenAPI Specification

Navigatiemenu

Zoeken