OpenAPI Specification
Deze gegevens zijn afkomstig van https://www.forumstandaardisatie.nl/open-standaarden/Openapi-specification
Over de standaard | |
---|---|
Lijst status | Verplicht (pas toe leg uit) |
Beschrijving | Beschrijven van REST APIs |
Uitleg | |
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. |
Waarvoor geldt de verplichting | OAS moet worden toegepast op het beschrijven/specificeren van een REST API. |
Aanvullende verplichtingen | |
Trefwoorden | Ruimtelijke ordening, Basisregistraties, Bodem, Geo-informatie |
Detailinformatie | |
Beheerorganisatie | OpenAPI Initiative |
Uitstekend beheer | Nee |
Specificatiedocument | https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md |
Volledige naam | OpenAPI Specification |
Versie | 3 |
Inkoop | |
Aandachtspunten | |
Sjabloon-bestektekst | |
CPV-code(s) | |
Implementatie | |
Conformiteitstest | |
Domein | |
Relatie met andere standaarden | |
Toelichting | |
Toetsingsinformatie | |
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/ |
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. |
Toelichting bij opname | |
Datum van aanmelding | 2017-04-24 |
Datum van besluit | 2018-05-25 |
Europese status (MSP) | Nee |
Documentatie |
|
Forum-Adviezen | |
Advies aan beheerder | |
Adoptieadviezen | |
Leveranciers |
- 20180222-Expertadvies-Open-API-Specification-0.pdf (Expertadvies,https://www.forumstandaardisatie.nl/sites/default/files/Downloads/Bijlagen OS/OpenAPI Specification/20180222-Expertadvies-Open-API-Specification-0.pdf,PDF Document)
- 20180401-Reacties-uit-openbare-consultatie-OAS-3.0.pdf (Consultatie,https://www.forumstandaardisatie.nl/sites/default/files/Downloads/Bijlagen OS/OpenAPI Specification/20180401-Reacties-uit-openbare-consultatie-OAS-3.0.pdf,PDF Document)
- 20221207-Intakeadvies-OAS-3.1-versiewijziging (Intakeadvies,https://www.forumstandaardisatie.nl/sites/default/files/BFS/3-lijsten/standaarden/openapi-specification/20221207-Intakeadvies-OAS-3.1-versiewijziging.pdf,PDF Document)
- Agp-4b-Hamerstuk-Standaardisatie-OBDO-24-mei-2018_3.pdf (Definitief,https://www.forumstandaardisatie.nl/sites/default/files/Downloads/Bijlagen OS/OpenAPI Specification/Agp-4b-Hamerstuk-Standaardisatie-OBDO-24-mei-2018 3.pdf,PDF Document)
- FS180425.3C-Forum-advies-OAS-3.0.pdf (Forumadvies,https://www.forumstandaardisatie.nl/sites/default/files/Downloads/Bijlagen OS/OpenAPI Specification/FS180425.3C-Forum-advies-OAS-3.0.pdf,PDF Document)
- Intakeadvies-Open-API-Specification.pdf (Intakeadvies,https://www.forumstandaardisatie.nl/sites/default/files/Downloads/Bijlagen OS/OpenAPI Specification/Intakeadvies-Open-API-Specification.pdf,PDF Document)