OpenAPI Specification

Standaarden

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

Alle eigenschappen

Inhoud Standaarden

• Standaarden
  • Beleid en praktijk rond standaarden op noraonline
• Alle standaarden
  • Lijst Pas Toe of Leg Uit Standaarden
  • Lijst Aanbevolen Standaarden
  • Overige standaarden
• Standaarden internationaal

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.

• Status op lijst van Forum Standaardisatie: Verplicht (pas toe leg uit)

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

• https://www.forumstandaardisatie.nl/standaard/openapi-specification
• https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md
• Beheerorganisatie: OpenAPI Initiative
  • https://www.openapis.org/

    Realiseert

    Lijst Open Standaarden voor Pas Toe of Leg Uit

Toepassing in voorzieningen en bouwstenen

Voorziening	Toelichting	Oordeel	Relevantie	Volgens bron	Gepubliceerd op
BRK (Basisregistratie Kadaster) BGT (Basisregistratie Grootschalige Topografie) WOZ (Basisregistratie Waarde Onroerende Zaken) BAG (Basisregistratie Adressen en Gebouwen)	Deze standaard is geïmplementeerd.	voldoet	van toepassing	Monitor Open Standaarden 2019	27 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).	voldoet	van toepassing	Monitor Open Standaarden 2019	27 maart 2020
BRV (Basisregistratie Voertuigen)	De BRV voldoet aan OpenAPI Specification.	voldoet	van toepassing	Monitor Open Standaarden 2019	27 maart 2020
HR (Basisregistratie Handelsregister)	Nieuwe of gewijzigde API’s van KVK voldoen hieraan. De oudere, bestaande nog niet, dit werk staat nu voor Q4 van 2022 gepland.	voldoet deels	van toepassing	Monitor Open Standaarden 2022	18 november 2022
MijnOverheid	Deze standaard wordt gebruikt voor de REST-API’s van MijnOverheid.	voldoet	van toepassing	Monitor Open Standaarden 2022	18 november 2022
Samenwerkende catalogi	De leverancier van de SC API (KOOP) geeft in Q1 2023 een indicatieve planning af m.b.t. het voldoen aan de standaard	voldoet niet	van toepassing	Monitor Open Standaarden 2022	18 november 2022
Website RDW.nl		voldoet	van toepassing	Monitor Open Standaarden 2022	18 november 2022
PDOK	Deze standaard is geïmplementeerd en wordt toegepast.	voldoet	van toepassing	Monitor Open Standaarden 2022	18 november 2022
TenderNed	De 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. We zijn aan het onderzoeken om onze Swagger specificaties om te zetten naar OAS 3.0 specificaties.	voldoet niet	van toepassing	Monitor Open Standaarden 2022	18 november 2022

Toelichting: Bouwstenen en gebruikte standaarden

De omschrijving van het functionele gebruik van de voorziening

Het domein (organisatorisch, taakvelden) binnen de overheid waarin het element (principe, standaard, voorziening..) wordt of kan worden toegepast. Bijvoorbeeld: gemeenten, provincies, waterschappen, Rijk, zorginstellingen, primair onderwijs.