Over de standaard

Beschrijving

Beschrijven van REST APIs

Lijst status
Verplicht (pas toe leg uit)

Uitleg

Nut

OpenAPI Specification (OAS) 3.0 is een standaard waarmee REST APIs op een uniforme, machineleesbare en implementatieonafhankelijke manier kunnen worden beschreven in JSON-formaat.  OAS geeft gebruikers een eenduidige en leesbare beschrijving van een REST API waarmee zij de interface zonder specifieke implementaties of software kunnen gebruiken.

OAS 3.0 zorgt er bovendien voor dat ontwikkelaars op een uniforme en inzichtelijke manier kunnen beschrijven wat een API doet, dat er minder leveranciersafhankelijkheid ontstaat en dat overheden meer hergebruik kunnen maken van elkaars ervaringen met betrekking implementatie van REST API’s.

Werking

Een REST API is zo effectief als de bijbehorende documentatie van de functionaliteit en structuur. De documentatie moet gemakkelijk te begrijpen zijn. Een OpenAPI Specification is een tekst (weergegeven in YAML- of JSON-indeling) die een standaard, programmeertaal-onafhankelijke beschrijving van een REST API geeft. OAS specificeert alleen welke functionaliteit het koppelvlak (de API) aanbiedt, niet welke implementatie of dataset er achter die API schuilgaat. Met OAS 3.0 kunnen zowel mensen als machines de functionaliteit van een REST API inzien, begrijpen en interpreteren, zonder dat er toegang tot de broncode, aanvullende documentatie of analyse van netwerkverkeer vereist is.

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.

Trefwoorden
Basisregistraties
Bodem
Geo-informatie
Ruimtelijke ordening

Detailinformatie

Beheerorganisatie
OpenAPI Initiative
Volledige naam
OpenAPI Specification
Version
3.0
Waarvoor geldt de verplichting

OAS moet worden toegepast op het beschrijven/specificeren van een REST API.

Implementatie

Domein
REST APIs
Document & (Web)Content
Hulpmiddelen

Om bestaande API specificaties om te zetten naar OAS3 zijn er verschillende converters die dit kunnen doen, hieronder enkele voorbeelden:

 

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:

 

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/

Community en Organisaties

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.

 

Toetsingsinformatie

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.

Datum van besluit
2018-05-25
Datum van aanmelding
2017-04-24