Forumadvies NLGov REST API Design Rules versie 2.0

Vergadering: Forum Standaardisatie woensdag 24 september 2025

Agendapunt: 4b

Aan: Forum Standaardisatie

Van: Stuurgroep Open Standaarden

Bijlagen:

1. Advies

Het Forum Standaardisatie adviseert versie 2.0) van NLGov REST API Design Rules te verplichten (‘Pas toe of leg uit’) via plaatsing op de ‘Pas toe of leg uit’-lijst van het Forum Standaardisatie.

De wijzigingen in de nieuwe versie hebben voor het huidige functioneel toepassingsgebied geen gevolgen, op een naamwijziging van ‘REST-API Design Rules’ naar ‘NLGov REST API Design Rules’ na. Het voorgestelde functioneel toepassingsgebied voor NLGov REST API Design Rules op de ‘Pas toe of leg uit’ lijst is daarmee:

“De standaard NLGov REST API Design Rules 2.0 moet worden toegepast bij het aanbieden van REST API’s ten behoeve van het ontsluiten van overheidsinformatie en/of functionaliteit.”

Advies is om de naam van de registratie REST-API Design Rules te behouden voor duurzame toegankelijkheid tot de informatie op REST-API Design Rules | Forum Standaardisatie en REST-API Design Rules - NORA Online.

Logius heeft het verzoek ingediend in aanmerking te komen voor het predicaat ‘Uitstekend beheer’ voor NLGov REST API Design Rules. Daarmee hoeven toekomstige kleine versiewijzigingen van de standaard in principe niet weer te worden getoetst. De toetsingsprocedure wijst uit dat NLGov REST API Design Rules voldoet aan het criterium ‘Open standaardisatieproces’, dusdanig om aan Logius het predicaat ‘Uitstekend beheer’ toe te kunnen kennen voor deze standaard.

In de rest van dit document is dit advies nader onderbouwd. Hoofdstuk 2 geeft een korte uitleg van het nut en belang van de standaard. Hoofdstuk 3 beschrijft het proces waarmee dit advies tot stand kwam, alsmede de vervolgstappen. Hoofdstuk 4 beschrijft de resultaten van de toetsing van de standaard op de inhoudelijke hoofdcriteria. Tot slot geeft hoofdstuk 5 aanvullende adviezen om de adoptie van de standaard te stimuleren.

2. Korte beschrijving van de standaard

2.1 Over de standaard

De standaard NLGov REST API Design Rules geeft een verzameling basisregels (design rules) 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 te ontwikkelen met REST API’s van de overheid.

In versie 2.0 zijn ten opzichte van versie 1.0 (die nu op de ‘Pas toe of leg uit’-lijst staat) zowel technische als inhoudelijke verbeteringen verwerkt. Versie 2.0 is modulair opgebouwd om de standaard flexibeler en beter toepasbaar te maken in verschillende contexten. De semantic versioning is uitgebreid. En verplichte modules zoals “Geospatial” en “Transport Security” zijn toegevoegd. Daarnaast zijn ook expliciete instructies voor testbaarheid toegevoegd via Developer.overheid.nl. De details van de wijzigingen in versie 2.0 zijn te vinden in de releasenotes.

2.2 Waarom is deze standaard belangrijk?

De standaard REST API Design Rules helpt ontwikkelaars van REST API’s (koppelvlakken over internet voor het bevragen van databronnen) op een uniforme en voorspelbare manier te ontwerpen. REST API’s van de overheid krijgen tijdens het ontwerp en de ontwikkeling ervan door toepassing van deze standaard een meer eenduidige structuur, wat wildgroei aan structuren voorkomt. Versie 2.0 van de standaard NLGov REST API Design Rules draagt bij aan het verder bevorderen van consistentie in het gegevenslandschap bij de digitale overheid. Dit zorgt voor een betere gegevensuitwisseling tussen overheidsorganisaties onderling en met bedrijven en burgers.

De wijzigingen in de nieuwe versie breiden de uniformiteit en eenduidigheid in het gebruik van REST API’s verder uit. Dit bevordert de interoperabiliteit tussen verschillende implementaties en voorkomt dat ontwikkelaars die met REST API’s van de overheid moeten werken steeds opnieuw het wiel moeten uitvinden. Bovendien draagt de nieuwe versie bij aan het verbeteren van de veiligheid van systemen door de toevoeging en verplichtstelling van de module “Transport Security”. De nieuwe versie is het uitgangspunt voor de ontwikkeling van REST API’s voor zowel het programma “Data bij de Bron” als het “Federatief Data Stelsel”.

3 Betrokkenen en proces

3.1 Gevolgde procedure

Logius heeft versie 2.0 van de standaard NLGov REST API Design Rules op 2 februari 2024 aangemeld voor plaatsing op de ‘Pas toe of leg uit’-lijst.

Procedurebegeleider InnoValor Advies heeft op 18 april 2024 een intakegesprek gevoerd met de indiener in aanwezigheid van Bureau Forum Standaardisatie. In dit gesprek is onderzocht of NLGov REST API Design Rules 2.0 voldoet aan de criteria om in procedure te worden genomen. De resultaten van het onderzoek zijn vastgelegd in het intakeadvies.

Op basis van het intakeadvies heeft het Forum Standaardisatie op 2 oktober 2024 besloten de standaard in procedure te nemen. Vervolgens heeft de procedurebegeleider in overleg met de indiener en Bureau Forum Standaardisatie een expertgroep samengesteld en een voorzitter aangesteld om de standaard te toetsen.

De leden van de expertgroep zijn op 22 mei 2025 bijeengekomen om de standaard te toetsen aan de criteria en geïdentificeerde aandachtspunten te bespreken. Tijdens deze bijeenkomst zijn ook het toepassings- en werkingsgebied vastgesteld. De uitkomst van het expertonderzoek is vastgelegd in het expertadvies.

Het Bureau Forum Standaardisatie publiceerde het expertadvies ter openbare consultatie via de website van Internetconsultatie van 24 juni 2025 tot 5 augustus 2025. In de openbare consultatie is één anonieme reactie ontvangen. De reactie is aansluitend voorgelegd aan de indiener van de standaard.

Dit Forumadvies is opgesteld op basis van het expertadvies, de reactie uit de openbare consultatie en inzichten van de leden van het Forum Standaardisatie. Indien het Forum Standaardisatie instemt met dit advies, wordt het aan het Overheidsbrede Beleidsoverleg Digitale Overheid (OBDO) ter besluitvorming voorgelegd.

3.2 Resultaat van het expertonderzoek

De geraadpleegde experts concluderen dat NLGov REST API Design Rules 2.0 voldoet aan alle hoofd- en subcriteria voor plaatsing op de ‘Pas toe of leg uit’-lijst van het Forum Standaardisatie. Zij adviseren bovendien om Logius het predicaat ‘Uitstekend beheer’ toe te kennen voor deze standaard, zodat toekomstige versies niet uitgebreid hoeven worden getoetst.

Er zijn geen criteria geïdentificeerd waaraan de standaard niet voldoet. Wel benoemen de experts enkele aandachtpunten:

Kosten en businesscase: De kosten voor de implementatie, met name voor de nieuwe verplichte Geospatial-module, zijn niet volledig inzichtelijk gemaakt en er is geen (kwalitatieve)businesscase opgesteld.
Backwards compatibility: Versie 2.0 is niet volledig backwards compatible door de modulaire opzet en nieuwe verplichte modules, maar dit wordt niet als belemmering gezien voor de adoptie.

Kortom, de geconsulteerde experts adviseren om NLGov REST API Design Rules 2.0 te verplichten aan de overheid via plaatsing op de 'Pas toe of leg uit'-lijst van het Forum Standaardisatie. De versiewijziging wordt gezien als waardevol voor het aanbieden van REST API’s ten behoeve van het ontsluiten van overheidsinformatie en/of functionaliteit.

3.3 Resultaat van de openbare consultatie

In de openbare consultatie werd één anonieme openbare reactie ontvangen. De volledige reactie is in het consultatieverslag bijgevoegd.

3.3.1 Reactie van Anoniem

De respondent vindt het vreemd om iets te verplichten dat primair bedoeld is als leidraad voor betere ontwikkelaars ervaring en interoperabiliteit. Volgens de respondent past dit meer bij een richtlijn waar gemotiveerd van afgeweken kan worden, wat in de praktijk overeenkomt met ‘Pas toe of leg uit’, maar waarbij de perceptie anders kan zijn voor implementerende partijen.

Belangrijkste punten uit de reactie:

Ontbreken van duidelijke nummering van de regels, wat discussie en wijzigingsbeheer zou vergemakkelijken.
Onvoldoende duidelijk wanneer een endpoint onder de standaard valt; sommige situaties passen mogelijk goed in het kader van de standaard.
Geen duidelijk ingangspunt voor feedback in de standaard zelf; respondent suggereert gebruik van GitHub-issues om feedback vanuit het werkveld te integreren.
De respondent stelt om in de toekomst ook beperkte academische vertegenwoordiging op te nemen in de samenstelling van de expertgroep.
Het feedbackproces is sterk gericht op het proces en de nota, minder op de inhoud van de standaard.

3.3.2 Reactie van de indiener (Logius) op Anoniem

Het toepassingsgebied van de standaard is voor het aanbieden van REST API’s. Andersoortige integraties, waaronder SOAP, hoeven hier niet aan te voldoen. Dit laat de gevraagde vrijheid dus toe. Inhoudelijke feedback wordt regelmatig geleverd door personen met verschillende achtergronden, inclusief academici. Dit leveren zij op via GitHub, waar de standaard ook naar linkt bij de ‘participate’ sectie. Mocht de respondent verdere (inhoudelijke) feedback willen leveren, dan nodigen wij hen uit om dit te doen op GitHub.

4. Toetsing op inhoudelijke criteria

Het Forum Standaardisatie hanteert vier inhoudelijke hoofdcriteria om te toetsen of een standaard in aanmerking komt voor verplichten (‘Pas toe of leg uit’) of aanbevelen aan de overheid.

Heeft de standaard toegevoegde waarde?
Zijn de standaard en het standaardisatieproces voldoende open?
Heeft de standaard voldoende draagvlak?
Is opname op de lijst een passend middel om de adoptie te bevorderen?

Ieder van deze hoofdcriteria heeft deelcriteria die staan beschreven op de website van het Forum Standaardisatie. Dit hoofdstuk beschrijft per criterium het resultaat van de toetsing.

4.1 Toegevoegde waarde

De toetsingsprocedure wijst uit dat NLGov REST API Design Rules 2.0 voldoet aan het criterium ‘Toegevoegde waarde’.

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

REST API’s worden gebruikt voor diverse koppelingen tussen overheden onderling, bedrijven en indirect tussen overheden en burgers. NLGov REST API Design Rules 2.0 heeft daarmee een generiek toepassingsgebied. De wijzigingen in versie 2.0 van de design rules zijn zowel technisch als inhoudelijk en zorgen voor meer duidelijkheid, testbaarheid en flexibiliteit

De nieuwe versie sluit tevens aan op de reeds opgenomen standaard OpenAPI Specification (OAS). Ook sluit NLGov REST API Design Rules 2.0 aan op de aanbevolen standaard Odata. Overlap met deze standaard wordt voorkomen door NLGov REST API Design Rules 2.0 alleen toe te passen op overheidsinformatie en enkelvoudige datasets. Er zijn geen concurrerende open standaarden die in aanmerking zouden kunnen komen op de ‘Pas toe of leg uit’-lijst of lijst aanbevolen standaarden.

4.2 Open standaardisatieproces

De toetsingsprocedure wijst uit dat NLGov REST API Design Rules 2.0 voldoet aan het criterium ‘Open standaardisatieproces, dusdanig om aan Logius het predicaat ‘Uitstekend beheer’ toe te kunnen kennen voor NLGov REST API Design Rules. De documentatie (specificatiedocument, ontwikkel- en beheerproces en overleggen) is vrij beschikbaar en toegankelijk via GitHub. Ook zijn eerdere versies van de standaard via het archief van GitHub te raadplegen. Ook toekomstige versievernieuwingen vallen onder het beheer van de standaard. Het beleid met betrekking tot (versie)beheer is gepubliceerd en staat beschreven in het beheerplan.

Het beheer van de standaard heeft een open governance en open procedure voor belanghebbenden om te kunnen participeren in het beheer. Het belang van de Nederlandse overheid en andere belanghebbenden is in het beheer van de standaard voldoende geborgd. Dit gebeurt via Kennisplatform API’s en Programmeringsraad GDI. Logius neemt hierin de rol van onafhankelijke, duurzame beheerpartij en facilitator en organiseert één keer per kwartaal overleggen over de doorontwikkeling en het beheer van de standaard. Belanghebbenden worden altijd uitgenodigd voor deze overleggen, maar de aanwezigen verschillen vaak afhankelijk van de wijzigingen die worden besproken.

De standaard heeft een Creative Commons Attribution 4.0 International Public License en is daarmee voor eenieder onherroepelijk vrij beschikbaar.

4.3 Draagvlak

De toetsingsprocedure wijst uit dat NLGov REST API Design Rules 2.0 voldoet aan het criterium ‘Draagvlak’.

De standaard NLGov REST API Design Rules 2.0 draagt bij aan interoperabiliteit zonder aanvullende afspraken en is voldoende ondersteund door leveranciers waar organisaties terecht kunnen om de standaard te implementeren. Versie 2.0 van NLGov REST API Design Rules is ontwikkeld op initiatief van organisaties in de stuurgroep van de Programmeringsraad GDI. In de stuurgroep zitten de belangrijkste stakeholders vanuit de overheid en zij staan achter de adoptie van de standaard. De standaard is getest en is door meerdere Nederlandse overheidsorganisaties in gebruik genomen. Een deel van deze afnemers worden vertegenwoordigd in de stuurgroep Kennisplatform API’s en programmeringsraad GDI.

Gebruikers kunnen de conformiteit van de implementatie toetsen via developer.overheid.nl. Ook zijn de daar aanwezige voorbeelden vrij te gebruiken.

4.4 Opname op de lijst bevordert adoptie

De toetsingsprocedure wijst uit dat NLGov REST API Design Rules 2.0 voldoet aan het criterium ‘Opname op de lijst bevordert adoptie’.

Dit is onder meer te danken aan de inhoudelijke verbeteringen in versie 2.0 op het vlak van betere toepasbaarheid, uitbreiding van semantic versioning, toevoeging van verplichte modules en toevoeging van expliciete instructies. Deze verbeteringen dragen bij aan een betere voorspelbaarheid, eenduidigheid en veiligheid van REST API’s binnen de overheid. Ze maken de implementatie concreter en toetsbaar, wat drempelverlagend werkt voor organisaties.

Daarnaast wordt de adoptie gestimuleerd doordat Logius actief inzet op adoptieondersteuning. Logius draagt hieraan bij door onder andere communicatie en kennisdeling via het Kennisplatform API’s, proactieve ondersteuning aan organisaties en ontwikkelaars, het automatiseren van controles en het aanbieden van automatische tools waarmee ontwikkelaars en organisaties eenvoudig kunnen toetsen of zij conform de standaard werken. Opname op de lijst biedt bovendien zekerheid aan kleinere organisaties en leveranciers: het geeft aan hen de garantie dat de standaard een duurzame investering is. Dit verlaagt de risico’s van implementatie en stimuleert een bredere marktadoptie.

5. Adviezen bij opname van de standaard

Het Forum Standaardisatie heeft geen aanvullende adviezen bij de versiewijziging van NLGov REST API Design Rules op de ‘Pas toe of leg uit’-lijst.

Documentatie-type

vergaderstuk