02-10-2024: Het Forum Standaardisatie heeft op 2 oktober 2024 ingestemd met het intakeadvies versiewijziging NLGov REST API Design Rules om de nieuwe versie van de standaard (2.0) in procedure te nemen voor plaatsing op de 'Pas toe of leg uit'-lijst. Een volledig expertonderzoek is aangewezen om de standaard te toetsen aan de criteria voor opname op de lijst. Het onderzoek hiervoor loopt momenteel. 

02-02-2024: Logius heeft REST-API Design Rules aangemeld bij Forum Standaardisatie om te toetsen of REST-API Design Rules in de nieuwe versie (2.0) geschikt is om te blijven verplichten aan de overheid.

REST-API Design Rules

REST-API Design Rules is een lijst afspraken die ontwikkelaars volgen tijdens het bouwen van een REST-API voor de publieke sector. Door de regels te hanteren wordt de API voorspelbaar. En dat is wel zo prettig voor andere ontwikkelaars die er gebruik van willen maken. Dankzij deze regels blijft het makkelijk voor organisaties om gegevens met elkaar uit te wisselen.

Inhoudsopgave

Content

Introductie

Voice over tekst REST-APIS

De overheid houdt waardevolle informatie over de gebouwen in Nederland zorgvuldig bij.

In een centrale database.

Maar hoe kan deze database worden ontsloten voor applicaties van anderen?

Daarvoor ontwikkelde het Kadaster een REST-API.

De REST-API laat de database razendsnel communiceren met andere applicaties.

Handig, als je bijvoorbeeld de weg zoekt.

Op woningjacht bent.

Of de brandweer uitrukt.

Zo kan heel Nederland profiteren van de informatie die via de database te raadplegen is.

Twee open standaarden spelen hierbij een cruciale rol: REST-API Design Rules.

En OpenAPI Specification.

Dankzij deze standaarden kunnen aanbieders van informatie hun database makkelijker openstellen voor anderen.

En houden softwaredevelopers meer tijd over voor verbetering van hun applicaties.

Meer weten? Ga naar forumstandaardisatie.nl.

Status

Lijst status
Verplicht (pas toe leg uit)
Functioneel toepassingsgebied

Beschrijft de toepassing(en) waarvoor het gebruik van de standaard verplicht is of aanbevolen wordt (afhankelijk van de lijststatus).

De standaard REST-API Design Rules moet worden toegepast bij het aanbieden van REST API’s ten behoeve van het ontsluiten van overheidsinformatie en/of functionaliteit.
Organisatorisch werkingsgebied

Benoemt de organisaties waarvoor de verplichting geldt.

Nederlandse overheden (Rijk, provincies, gemeenten en waterschappen) en instellingen uit de (semi-) publieke sector.
Europese status
Nee

Nut en werking

Typering
Verzameling regels voor het structureren en documenteren van REST API’s.
Nut

De overheid ontsluit gegevens en applicaties steeds vaker met REST-API's. Voorbeelden hiervan zijn te zien op de website developer.overheid.nl, in Common Ground, Haal Centraal en het Digitaal Stelsel Omgevingswet.

Representational state transfer (REST) is een ontwerpprincipe dat wereldwijd veel gebruikt wordt voor het bouwen van programmeerinterfaces over het web (API's). REST is geen standaard maar een ontwerpprincipe, en laat nog veel vrijheid in het structureren van API's.

De standaard REST-API Design Rules geeft een verzameling basisregels voor structuur en naamgeving waarmee de overheid op een uniforme en eenduidige manier REST-API's aanbiedt. Dit maakt het voor ontwikkelaars gemakkelijker om betrouwbare applicaties met te ontwikkelen met API's van de overheid.

 
Werking

Een application programming interface (API) is een gestructureerd en gedocumenteerd koppelvlak voor communicatie tussen applicaties. Zo lang er computers zijn, bestaan er API's en worden er verschillende API technologieën gebruikt. In de laatste 10 jaar 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 over het Internet beschikbaar voor andere applicaties. De technologie achter websites en REST-API's heeft daarom veel gemeen.

De overheid gebruikt REST-API's voor koppelingen met andere overheden, bedrijven en indirect ook met burgers, bijvoorbeeld via mobiele apps en webapps die aangeboden worden door bedrijven of overheden zelf. Ontwikkelaars kunnen deze REST-API's bevragen vanuit de gangbare programmeertalen en frameworks zoals Python, Java, Microsoft C#, PHP.

De standaard REST-API Design Rules 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.

De REST-API Design Rules moeten toegepast worden daar waar de overheid REST-API's inzet, maar verplicht niet het gebruik van REST-API's bij het ontsluiten van gegevens of functionaliteit.
Domein
Relatie met andere standaarden
Trefwoorden

Detailinformatie

Volledige naam

REST API Design Rules
Versie
1.0
Specificatiedocument

REST API Design Rules
Beheerorganisatie
Logius

Toetsingsinformatie

Uitstekend beheer
Nog niet getoetst
Intakeadvies

Intakeadvies_API_Design_Rules.pdf

PDF Document | 210.52 KB
Expertadvies

Expertadvies-standaard-REST-API-Design-Rules-1.0.pdf

PDF Document | 420.3 KB
Forumadvies

Forumadvies-REST-API-Design-Rules.pdf

PDF Document | 216.35 KB
Datum van aanmelding

15-10-2019
Datum besluit

09-07-2020

Toepassing

Praktijkvoorbeelden

Overig

Toelichting bij opname

De standaard verplicht niet het gebruik van REST-API's

Als een overheidsorganisatie investeert in de bouw van REST-API's, dan moeten deze  aangeboden worden volgens de REST-API design rules. De standaard zelf verplicht echter niet het gebruik van REST-API's om gegevens of functionaliteit te ontsluiten. Hiervoor kunnen als vanouds ook Webservices (SOAP-API's), (linked) open data of andere koppelvlakken gebruikt worden.

Beheer onder Logius

De standaard REST-API Design Rules is ontwikkeld in het Kennisplatform API's door een brede groep organisaties. Vanaf medio 2020 ligt het beheer van de standaard formeel bij Logius. Het Kennisplatform API's blijft wel input leveren voor de doorontwikkeling van de standaard.

Veranderend gegevenslandschap

De groeiende inzet van REST-API's bij de overheid raakt bestaande standaarden zoals Digikoppeling en StUF. Logius, VNG, Forum Standaardisatie en het Kennisplatform API's werken samen aan een visie over de transitie naar een nieuw gegevenslandschap en hoe REST-API's, Digikoppeling en StUF daarin samenhangen. Hierover volgt nog een publicatie.
Adoptieadviezen

De formele adoptieadviezen die het Forum Standaardisatie meegeeft bij plaatsing van de standaard op de 'Pas toe of leg uit'-lijst of lijst aanbevolen standaarden.
  • Aan Forum Standaardisatie om duidelijkheid te geven over de samenhang tussen verschillende standaarden –met name de samenhang tussen StUF en standaarden gerelateerd aan API’s– eventueel door het publiceren van een beslisboom.
     
  • Aan Logius (beheerder Digikoppeling) om expliciet aandacht te geven aan de samenhang en transitie van Digikoppeling en REST API Design Rules.
     
  • Aan Logius als beheerorganisatie om te waken voor een evenredige vertegenwoordiging van verschillende disciplines (zoals ontwikkelaars, ontwerpers, architecten en beleidsmakers) in de werkgroep bij het ontwikkel- en beheerproces van de standaard.
     
  • Aan de Werkgroep API Design Rules van het Kennisplatform API's om te werken aan verdere inhoudelijke ontwikkeling van de standaard om deze volwassener te maken en openstaande technische ‘issues’ weg te werken. Het Kennisplatform API's heeft toegezegd hier zo snel mogelijk mee aan de slag te gaan.