Bewerken pagina: FS:Openapi-specification

U hebt geen toestemming om deze pagina te bewerken, want:

• De gevraagde handeling is voorbehouden aan gebruikers in een van de volgende groepen: gebruikers, beheerders, projectlid, secretaris.
• U hebt geen rechten om de gevraagde handeling te verrichten.

Vul in dit formulier alle gegevens in van de standaard. Kies de (eventueel verkorte) naam van de standaard als paginanaam.

Elementtype^*

Het elementtype waaronder deze pagina valt. U kunt dit niet wijzigen omdat het formulier is afgestemd op het elementtype.

:

Status toelichting

Leg hier uit waarom de pagina niet 'actueel' is, bijvoorbeeld waar het door is vervangen of wanneer het is vervallen. Leg ook links naar RFC's et cetera.

:

Status historie

per bulletpoint (regel beginnend met spatie) op welke datum, welke beheer-handeling is begonnen. met eventueel daarachter een toelichting.

:

Concept-pagina FS^*

als dit 'Ja' is, wordt de pagina niet gepubliceerd als RDF en wordt de pagina niet in bepaalde overzichten getoond.

:

 Ja  Nee

Melding bovenaan pagina

:

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

Titel

Wordt weergegeven titel van de pagina (zo lang de pagina in de standaard naamruimte staat). Bijzondere eigenschap, wordt gebruikt door de extensie "Semantic Title"

:

Introductie

Samenvatting die bovenaan de pagina staat

:

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 Forum Standaardisatie

:

In behandelingAanbevolenVerplicht (pas toe leg uit)ArchiefStreefbeeldafspraakWettelijk verplicht

Functioneel toepassingsgebied

Beschrijf in welk functioneel gebied deze standaard toegepast dient te worden. Let wel, wijzigen van functioneel toepassingsgebied vindt alleen plaats als uitkomst van een toetsingsprocedure

:

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

Organisatorisch werkingsgebied

Het organisatorische terrein waarbinnen de standaard van werking is. Let wel, wijzigen van functioneel toepassingsgebied vindt alleen plaats als uitkomst van een toetsingsprocedure

:

Aanvullende verplichtingen

Beschrijf eventuele aanvullende verplichtingen bij toepassing van deze standaard.

:

Opgenomen op Europese lijst MSP^*

:

 Ja  Nee

Typering Forum Standaardisatie

:

Nut

Bijdrage aan interoperabiliteit

:

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

Werking van de standaard: wat doet het?

:

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 [https://yaml.org/spec/ YAML] of [https://www.forumstandaardisatie.nl/open-standaarden/json/ 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 FS-standaarden

niet verder gedefinieerde relevantie van een andere standaard

:

Domein Forum Standaardisatie

Indeling in domeinen zoals gehanteerd door Forum Standaardisatie

:

Trefwoorden Forum Standaardisatie

:

Ruimtelijke ordeningBasisregistratiesBodemGeo-informatie

Gangbaar

:

 Geen/onbekend  Ja  Nee

Volledige naam

De volledige naam (afkortingen uitgeschreven)

:

Versie

Versie van de standaard(en) die door het Bureau Forum Standaardisatie is opgenomen

:

Specificatiedocument

Links naar de specificatiedocument(en) van deze versie van de standaard

:

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md

Beheerorganisatie

Beheerorganisatie

:

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. 

Implementatiehulpmiddelen

:

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://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

Hoe te controleren of een systeem/dienst voldoet aan de standaard

:

Praktijkvoorbeelden

Tijdelijk veld totdat er 'Praktijkvoorbeelden' als proxy-element zijn die praktijkvoorbeelden koppelen met meerdere standaarden

:

Toelichting bij opname lijst Forum Standaardisatie

:

Het Forum Standaardisatie heeft [https://www.forumstandaardisatie.nl/sites/default/files/FS/2023/0614/FS-20230614.3-Oplegnotitie-Open-Standaarden-Lijsten.pdf 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

Adviezen vanuit het Forum Standaardisatie aan diverse betrokkenen om de adoptie van de standaard te bevorderen.

:

Uitstekend beheer

Indicatie of het beheer voldoet aan de door het Forum Standaardisatie gestelde normen voor uitstekend beheer

:

 Geen/onbekend  Ja  Nee  Nog niet getoetst

Aanmelder

:

Documentatie voor opname lijst FS

:

Datum van aanmelding lijst Forum Standaardisatie

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.

:

Datum van besluit lijst Forum Standaardisatie

:

Waarvoor geldt de verplichting

Uitleg voor welke groepen of organisaties de verplichting wel en niet geldt

:

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

Toelichting relatie met andere FS-standaarden

:

Aandachtspunten

Beschrijf de eventuele aandachtspunten voor toepassing van de standaard.

:

Advies aan beheerder

Advies van de expert die de opname begeleidde aan de beheerder van de standaard.

:

Sjabloon-bestektekst

Voorbeeld bestektekst om de standaard te eisen bij inkoop

:

CPV-code

categorie-code voor inkoop

:

Leveranciers

:

Video

Informatie over de video

:

Relatie met andere FS-standaarden

:

Vrije tekstU kunt hier extra informatie toevoegen. Deze zal onderaan de pagina getoond worden, maar is niet opvraagbaar via query's.

:

Meta-informatie

Samenvatting bewerkingU kunt hier een samenvatting of reden van de bewerking opgeven.

:

Samenvatting:

Dit is een kleine wijziging

Volg deze pagina

Pagina opslaan   Bewerking ter controle bekijken   Wijzigingen bekijken   Annuleren