Main content

Via API's kunnen applicaties gegevens uitwisselen. Hoe, wanneer en onder welke voorwaarden je gegevens uitwisselt beschrijven we in de architectuur en standaarden. Op deze pagina is een globaal overzicht opgenomen van deze standaarden. Meer details over de standaarden en het beheer ervan is te vinden op het tabblad Documentatie en onze github-omgeving. Hoe API’s zich verhouden tot de enterprise,– en/of solution architectuur is onder andere beschreven in de NORA.  

API-standaarden

Voor het ontwikkelen van API's en de beveiliging van de gebruikerstoegang tot API's bestaan standaarden. Logius beheert twee van die API-standaarden:

Voor wie zijn deze standaarden? 

De standaarden staan op de lijst met verplichte open standaarden van het Forum Standaardisatie. Overheden moeten deze standaarden dus toepassen

Dit betekent dat de API Design Rules moet worden toegepast bij het aanbieden van REST-API’s voor het ontsluiten van overheidsinformatie of functionaliteit.

NLGov OAuth moet worden toegepast wanneer rechthebbende gebruikers of 'resource owners' van een applicatie via impliciete of expliciete toestemming een dienst van een derde toegang geven tot die applicatie om gegevens via een REST-API te gebruiken.

NLGov OpenID connect moet worden toegepast bij het beschikbaar stellen en het gebruiken van federatieve authenticatiediensten, inclusief vertegenwoordiging en attribuutverstrekking.

ADR (ook: de REST-API Design Rules)

De REST-API Design Rules (ADR) zijn een standaard voor het ontwikkelen van zogenoemde REST-API's. REST staat voor REpresentational State Transfer. REST-API's doen voor applicaties wat websites voor mensen doen: websites presenteren informatie aan mensen, REST-API's maken applicaties en gegevens via internet beschikbaar voor andere applicaties. De ADR zijn een verzameling basisregels voor structuur en naamgeving van REST-API's.

De overheid gebruikt REST-API's voor koppelingen met andere overheden, bedrijven en ook met burgers, bijvoorbeeld via mobiele apps of webapps die aangeboden worden door bedrijven of overheden zelf. REST-API's maken het voor ontwikkelaars gemakkelijker om betrouwbare applicaties te ontwikkelen met API's van de overheid. De REST-ADR-standaard is daarbij een extra hulpmiddel. 

De REST-API Design Rules (ADR) hebben tot doel om meer uniformiteit te brengen in de manier waarop de overheid REST-API's aanbiedt. Met dit doel beschrijft de standaard een aantal basisregels voor het structureren en documenteren van REST-API's. De ADR moeten toegepast worden daar waar de overheid REST-API's inzet. Het gebruik van REST-API's bij het ontsluiten van gegevens of functionaliteit is op zichzelf niet verplicht.

OAuth-NL (ook: het NL GOV OAuth profile)

OAuth is een beveiligingstandaard voor het autoriseren van toegang tot REST API’s. Het NL GOV-profiel op OAuth 2.0 legt bindende afspraken vast over het gebruik van de standaard OAuth 2.0 bij de Nederlandse overheid. In combinatie met onderliggende standaard OAuth 2.0 zorgt het NL GOV-profiel ervoor dat de autorisatie van gebruikers van REST-API's van de overheid op een uniforme en eenduidige manier gebeurt.

OAuth 2.0 is een open standaard voor de beveiliging van applicaties die gegevens uitwisselen met behulp van REST-API’s. Met OAuth 2.0 kunnen gebruikers een website of webapplicatie autoriseren om hun persoonlijke gegevens via een REST-API op te halen bij een ander systeem, zonder daarbij hun gebruikersnaam en wachtwoord uit handen te geven. OAuth 2.0 maakt hiervoor gebruik van een techniek (via tokens) die toegang geeft tot specifieke gegevens van een gebruikersaccount voor een bepaalde duur. 

OAuth 2.0 is een generieke standaard die meestal nog aanvullende afspraken vereist voor de toepassing in specifieke domeinen. Het NL GOV OAuth-profiel legt dit soort nadere afspraken vast voor het gebruik van OAuth 2.0 bij de Nederlandse overheid. Zo bepaalt het profiel hoe applicaties zich bij elkaar moeten registreren en hoe autorisatiecodes veilig uitgewisseld moeten worden. OAuth 2.0 laat daarin bijvoorbeeld veel implementatieopties vrij. Dit komt de interoperabiliteit niet ten goede, daarom beperkt het NL GOV OAuth-profiel het aantal opties. 

Digikoppeling REST Profiel

Situaties waarbij met de Digikoppeling standaarden toepast kunnen ook gebruik maken van de API standaarden. Door het Digikoppeling REST profile toe te passen kunnen API’s worden ingezet die compatible zijn met de API Standaarden. Bekijk de Digikoppeling-documentatie voor meer details.

OIDC-NL (ook: het NL GOV-profiel op de Open ID Connect-standard)

Het NL GOV Assurance profile for OIDC 1.0 geeft door dienstverleners aangeboden diensten de mogelijkheid om de identiteit van een eindgebruiker te controleren gebaseerd op verschillende authenticatieservices (zoals DigiD), waarbij profielinformatie van de eindgebruiker volgens een gestandaardiseerde wijze beschikbaar wordt gesteld aan de daarvoor geautoriseerde diensten.

Het profiel maakt het mogelijk dat gebruikers zelf een keuze kunnen maken voor een (goedgekeurde) authenticatievoorziening, zoals DigiD, en niet steeds opnieuw in hoeven te loggen, bijvoorbeeld wanneer er gebruik wordt gemaakt van een routeringsvoorziening.

OpenID Connect is een generieke standaard die meestal nog aanvullende afspraken vereist voor de toepassing in specifieke domeinen. NL GOV Assurance Profile for OIDC legt nadere afspraken vast over het gebruik van OpenID Connect bij de Nederlandse (semi-)overheid.
 

Overige API-gerelateerde standaarden

Verlichte standaarden die veel in relatie tot API’s worden gebruikt zijn de OpenAPI Specification voor heb beschrijven van API’s en de TLS standaard voor het versleutelen van de connectie waar de API gebruik van maakt.

Aanbevolen standaarden die veel in relatie tot API’s worden gebruikt zijn HTTPS, DNS, JSON, Oauth, OIDC, TCP/IP, X509 & XML.

Zie ook