OpenAPI Specification

Uit NORA Online
Naar navigatie springen Naar zoeken springen


Onderdeel van
Lijsten & Verwijzingen
Contact
NORA Beheer
nora@ictu.nl
Status
Actueel
Status is afgeleid van Status bij Forum Standaardisatie (Verplicht (pas toe leg uit)
Naam
OpenAPI Specification
ID

OpenAPI Specification

Type

Standaard

Versie
3.0
Wijzigingsdatum
Laag Vijflaagsmodel
Sjabloon:Titel laag0, 1
Deze informatie is (deels) overgenomen van forumstandaardisatie.nl.
Schaduwkopie: OpenAPI Specification


Beschrijven van REST APIs
Publicatie 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.


Waar toepasbaar

  • 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.
  • Waarvoor geldt de verplichting: OAS moet worden toegepast op het beschrijven/specificeren van een REST API.

Meer informatie

Toepassing in voorzieningen en bouwstenen

VoorzieningToelichtingOordeelRelevantieVolgens bronGepubliceerd op
BRK (Basisregistratie Kadaster)
BGT (Basisregistratie Grootschalige Topografie)
WOZ (Basisregistratie Waarde Onroerende Zaken)
BAG (Basisregistratie Adressen en Gebouwen)
Deze standaard is geïmplementeerd.voldoetvan toepassingMonitor Open Standaarden 201927 maart 2020
BRO (Basisregistratie Ondergrond)Het Bronhouderportaal BRO (voorportaal voor validatie van BRO gegevens voordat deze worden door geleverd naar de Landelijke Voorziening BRO) voldoet aan de open API specificatie https://www.bronhouderportaal-bro.nl/bpbro-frontend/documentation/api.html. De Landelijke Voorziening BRO voldoet aan de PTOLU Digikoppeling standaard (SOAP-XML).voldoetvan toepassingMonitor Open Standaarden 201927 maart 2020
BRV (Basisregistratie Voertuigen)De BRV voldoet aan OpenAPI Specification.voldoetvan toepassingMonitor Open Standaarden 201927 maart 2020
HR (Basisregistratie Handelsregister)KvK gebruikt deze specificatie actief. Reeds operationele API's worden geleidelijk aangepast.voldoet deelsvan toepassingMonitor Open Standaarden 202011 februari 2021
MijnOverheidDeze standaard wordt gebruikt voor de REST-API's van MijnOverheid.voldoetvan toepassingMonitor Open Standaarden 202011 februari 2021
Samenwerkende catalogiSamenwerkende catalogi voldoet aan deze standaard.voldoetvan toepassingMonitor Open Standaarden 202011 februari 2021
Website RDW.nlDe BRV voldoet aan Open API Specification.voldoetvan toepassingMonitor Open Standaarden 202011 februari 2021
PDOKDeze standaard is geïmplementeerd en wordt toegepast.voldoetvan toepassingMonitor Open Standaarden 202011 februari 2021
TenderNedDe publieke API's worden beschreven door middel van Swagger. Swagger kan je zien als OAS versie 2.0. Swagger als API Specificatie bestaat niet meer en is opgegaan in OAS. TenderNed voldoet daarmee niet aan OAS 3.0. Deze versie is belangrijk omdat deze samenhang aanbrengt in de verschillende manieren om API specificaties op te stellen.voldoet nietvan toepassingMonitor Open Standaarden 202011 februari 2021
Toelichting: Bouwstenen en gebruikte standaarden