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)

OpenAPI Specification

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.

Inhoudsopgave

    Content

    Introductie

    Voice over tekst REST-APIS

    De overheid houdt waardevolle informatie over de gebouwen in Nederland zorgvuldig bij.

    In een centrale database.

    Maar hoe kan deze database worden ontsloten voor applicaties van anderen?

    Daarvoor ontwikkelde het Kadaster een REST-API.

    De REST-API laat de database razendsnel communiceren met andere applicaties.

    Handig, als je bijvoorbeeld de weg zoekt.

    Op woningjacht bent.

    Of de brandweer uitrukt.

    Zo kan heel Nederland profiteren van de informatie die via de database te raadplegen is.

    Twee open standaarden spelen hierbij een cruciale rol: REST-API Design Rules.

    En OpenAPI Specification.

    Dankzij deze standaarden kunnen aanbieders van informatie hun database makkelijker openstellen voor anderen.

    En houden softwaredevelopers meer tijd over voor verbetering van hun applicaties.

    Meer weten? Ga naar forumstandaardisatie.nl.

    Status

    Lijst status
    Verplicht (pas toe leg uit)
    Functioneel toepassingsgebied

    Beschrijft de toepassing(en) waarvoor het gebruik van de standaard verplicht is of aanbevolen wordt (afhankelijk van de lijststatus).

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

    Benoemt de organisaties waarvoor de verplichting geldt.

    Nederlandse overheden (Rijk, provincies, gemeenten en waterschappen) en instellingen uit de (semi-) publieke sector.
    Europese status

    ‘Ja’ betekent dat de standaard is erkend door het Multi Stakeholder Platform on ICT Standardisation van de Europese Commissie.
    Nee

    Nut en werking

    Typering
    Beschrijven van REST APIs
    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.
    Domein
    Relatie met andere standaarden
    OAuth
    Relatie met andere standaarden
    SAML
    Trefwoorden

    Detailinformatie

    Volledige naam

    OpenAPI Specification
    Versie
    3.0
    Specificatiedocument

    Open API Specification
    Beheerorganisatie
    OpenAPI Initiative

    Toepassing

    Community

    Organisaties waar men terecht kan voor adoptieondersteuning, best practices, use cases en informatie over de standaard.

    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

    Vrij beschikbare hulpmiddelen en software die de adoptie van de standaard ondersteunen. Dit kunnen zijn: referentie-implementaties, open source libraries, test tools, e.d.

    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/

    Toetsingsinformatie

    Uitstekend beheer
    Nee
    Expertadvies

    20180222-Expertadvies-Open-API-Specification-0.pdf

    PDF Document | 855.29 KB
    Consultatie

    20180401-Reacties-uit-openbare-consultatie-OAS-3.0.pdf

    PDF Document | 102.33 KB
    Definitief

    Agp-4b-Hamerstuk-Standaardisatie-OBDO-24-mei-2018_3.pdf

    PDF Document | 158.03 KB
    Forumadvies

    FS180425.3C-Forum-advies-OAS-3.0.pdf

    PDF Document | 835.24 KB
    Intakeadvies

    Intakeadvies-Open-API-Specification.pdf

    PDF Document | 394.59 KB
    Intakeadvies

    20221207-Intakeadvies-OAS-3.1-versiewijziging.pdf

    PDF Document | 175.6 KB
    Datum van besluit

    Datum waarop het Overheidsbreed Beleidsoverleg Digitale Overheid (OBDO) heeft besloten de standaard op de lijst te plaatsen.

    25-05-2018
    Datum van aanmelding

    Datum waarop een organisatie de standaard heeft aangemeld voor opname op de lijst van aanbevolen of verplichte open standaarden. Als een standaard voldoet aan de criteria om in behandeling genomen te worden, vindt een toetsingsprocedure plaats. Deze duurt ongeveer een 6 maanden.

    24-04-2017

    Overig

    Waarvoor geldt de verplichting

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