API Strategie
Samen met Bureau Forum Standaardisatie, Kamer van Koophandel, VNG Realisatie, Logius en het Kadaster is Geonovum het Kennisplatform API's gestart. In dit Kennisplatform delen we kennis over het toepassen van API's en maken we afspraken over de structuur van API's voor overheidsorganisaties. Deze afspraken landen in de Nederlandse API Strategie.
Intentieverklaring API Strategie
Verschillende overheidsorganisaties hebben een intentieverklaring ondertekend waarmee zij zich ervoor uitspreken om API’s te structureren conform de afspraken in de API Strategie. Deze intentieverklaring is opgesteld om samenwerking tussen partijen die binnen de overheid met API’s en standaarden werken te bevorderen.
API Strategie
Een application programming interface (API) is een gestructureerd en gedocumenteerd koppelvlak voor communicatie tussen applicaties. Het meest actuele overzicht van alle API documentatie in de API Strategie vind je op de Github pagina van het Kennisplatform.
De API strategie omvat algemene onderdelen, zoals een beschrijving van architectuur en gebruikerswensen. Daarnaast is er een normatief deel dat op de lijst met verplichte standaarden van de Nederlandse overheid staat. In het normatieve deel van de API Strategie vind je:
- NL GOV OAuth profiel (OAuth)
- Open API specification (OAS)
- API Design Rules (ADR)
- Geospatial module
- NL GOV OIDC
- Digikoppeling REST API koppelvlak
- Signing module
- Encryptie module
Daarnaast zijn er nog een aantal functionele en technische modules zoals de modules voor API Access, Hypermedia en Naming Conventions. Zie de Github pagina van het Kennisplatform API's voor een compleet overzicht.
Hieronder geven we een korte beschrijving van de toepassing van OAuth, de Open API specificatie, de API Design Rules en de Geomodule.
NL GOV Assurance profile for OAuth
Het OAuth 2.0-profiel is een profiel voor de beveiliging van API's en dan met name REST-API's.
De OAuth 2.0-specificaties zijn geschikt voor een breed scala aan implementaties met verschillende beveiligings- en bruikbaarheidsoverwegingen, voor verschillende soorten softwareclients. De profielen voor de OAuth 2.0-client, beveiligde bron en autorisatieserver die in het OAuth profiel worden gedefinieerd, hebben twee doelen:
- Een verplichte basisset van beveiligingscontroles te definiëren die - met behoud van een implementatiegemak en functionaliteit - geschikt zijn voor een breed scala aan gebruiksscenario's door de overheid;
- Optionele, geavanceerde beveiligingscontroles te definiëren voor gevoelige gebruiksscenario's waarbij een verhoogd risico strengere controles rechtvaardigt.
OpenAPI Specification (OAS)
Een application programming interface (API) is een gestructureerd en gedocumenteerd koppelvlak voor communicatie tussen applicaties. Een OpenAPI Specification (OAS) beschrijft 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. De documentatie van een API moet voor machines leesbaar en voor mensen begrijpelijk zijn.
OAS specificeert alleen welke attributen de API verwerkt en hun datatypen, niet welke implementatie er achter de API schuilgaat. OAS is dus een beschrijvende taal en heeft geen binding met specifieke programmeertalen. Een specificatie conform OAS is een tekstbestand met een gestandaardiseerde YAML of JSON structuur. Daardoor is OAS zowel leesbaar voor machines als begrijpelijk voor mensen en kunnen zij beiden de dataset attributen van een REST API vinden, bekijken en verwerken zonder toegang tot de programmatuur en zonder aanvullende documentatie.
De OpenAPI Specification is -net als de basisset geo-standaarden- onderdeel van het Nederlands uitwisselingsfundament van standaarden. Je vindt het volledig overzicht op de OpenAPI Specification pagina van het Forum Standaardisatie.
REST-API Design Rules (ADR)
In de laatste jaren heeft Representational state transfer (REST) zich ontwikkeld tot een bepalend principe voor het realiseren van API's. Zogenaamde ‘REST-API's’ doen voor applicaties wat websites voor mensen doen. Websites presenteren informatie aan mensen, REST-API's maken applicaties en gegevens beschikbaar voor andere applicaties. De technologie achter websites en REST-API's heeft veel overeenkomsten.
De overheid gebruikt REST-API's om koppelingen te maken met andere overheden, bedrijven en via mobiele apps en webapps. Ontwikkelaars kunnen deze REST-API's bevragen vanuit de gangbare programmeertalen en frameworks zoals Python, Java, Microsoft C#, PHP of javascript.
REST-API Design Rules is een lijst afspraken die ontwikkelaars volgen tijdens het bouwen van een REST-API voor de publieke sector. Het heeft tot doel om meer uniformiteit te brengen in de manier waarop de overheid REST-API's aanbiedt. Hiervoor beschrijft de standaard een aantal basisregels voor het structureren en documenteren van REST-API's.
Je vindt het volledig overzicht op de pagina REST-API Design Rules van het Forum Standaardisatie.
Geo module
De geo module of Geospatial Module is een normatieve uitbreiding op de REST-API Design rules met regels voor ruimtelijke gegevens en functies in APIs. De geo module is gebaseerd op OGC API Features. Geonovum is betrokken geweest bij de totstandkoming van deze module, die nu in beheer is bij Logius.