NL API Design Rules: regels en linter

De API Design Rules (ADR) beschrijven hoe een overheids-API zijn paden, parameters, fouten en versies hoort in te richten, zodat ontwikkelaars niet bij elke API opnieuw hoeven te leren hoe die werkt. De publicatie noemt als doel "increasing developer experience (DX) and interoperability between APIs". De rest van de pagina gaat over versie 2.2.0.

Versies en data komen uit de publicatie van Logius en de pagina van het Forum Standaardisatie. Voor het gebruik bij geodata, zie WFS en OGC API Features; de conformance-lijst van de OGC API van PDOK verwijst zelf naar de ADR-publicatie.

NLGov REST API Design Rules staan op de lijst Pas toe of leg uit, in versie 2.2. De pagina van het Forum Standaardisatie noemt twee besluitdata, 9 juli 2020 en 25 november 2025, en twee versiewijzigingen via Uitstekend beheer: naar 2.1 en naar 2.2 (documenten van 22 december 2025 en 15 mei 2026). Uitstekend beheer betekent dat een nieuwe versie zonder aanvullende toetsing wordt overgenomen. Het Forum legt het toepassingsgebied vast:

Als een overheidsorganisatie investeert in de bouw van REST-API's, dan moeten deze aangeboden worden volgens de REST-API design rules.

Bron: Forum Standaardisatie, pagina REST-API Design Rules, toelichting bij opname. De standaard verplicht volgens dezelfde pagina niet het gebruik van REST-API's: SOAP-koppelingen, linked open data en andere koppelvlakken blijven mogelijk. Het organisatorisch werkingsgebied is Nederlandse overheden (Rijk, provincies, gemeenten en waterschappen) en instellingen uit de (semi-)publieke sector. Sinds 9 december 2025 heet de standaard NLGov REST API Design Rules; de registratie behoudt de oude naam.

Voor een gemeente die een open data-API publiceert, komt dit samen met de metadata-eisen uit DCAT-AP-NL. Over de gemeentelijke architectuur waar API’s in passen, zie Common Ground.

De publicatie scheidt technische regels, die automatisch toetsbaar horen te zijn, van functionele regels die u bij het ontwerp afweegt. De volgende regels veroorzaken in de praktijk de meeste afwijkingen.

Letterlijk over de slash-regel:

A URI MUST NOT contain a trailing slash. When requesting a resource including a trailing slash, this MUST result in a 404 (not found) error response and not a redirect.

Bron: Logius, NLGov REST API Design Rules 2.2.0, regel /core/no-trailing-slash. Wie dus zowel /gebouwen als /gebouwen/ laat werken, overtreedt de regel. De hoofdresource van de service mag wel eindigen op een slash.

Een API die voldoet, laat het hoofdversienummer in de URI staan en meldt het volledige versienummer in elk antwoord. De publicatie zegt over het versienummer in de URI: "The URI of an API (base path) MUST include the major version number, prefixed by the letter v." Over het volledige nummer: "The API-Version header MUST be returned in a response header in every response." Een voorbeeld is https://api.voorbeeld.example/v1/gebouwen met in het antwoord API-Version: 1.0.0.

Voor fouten schrijft de publicatie RFC 9457 voor:

Error responses with HTTP status codes 4xx or 5xx MUST use either application/problem+json or application/problem+xml as the Content-Type header, and the response body MUST conform to the structure defined in [RFC9457].

Bron: Logius, ADR 2.2.0, regel /core/error-handling/problem-details. Een ongeldig verzoek hoort bovendien status 400 te krijgen (/core/error-handling/invalid-input). De linter controleert dit in de OpenAPI-beschrijving: elk endpoint met parameters moet een 400-respons beschrijven, en die respons moet een problem-schema met status, title en detail hebben. Meer over het ontwerp van een koppeling staat op API-koppelingen.

Ja. De ADR-publicatie bevat als bijlage A een configuratie voor Spectral, een open source linter voor OpenAPI-bestanden. In die bijlage staat dat de configuratie "tevens gehost" wordt op developer.overheid.nl. Het bestand linter.yaml uit de 2.2.0-publicatie is op 11 oktober 2026 op twee voorbeeld-OpenAPI-bestanden gedraaid met Spectral CLI 6.17.0 (6.15.0 gaf dezelfde uitkomst). Het fictieve bestand api-fout.yaml overtreedt bewust de regels:

openapi: 3.0.3
info:
  title: Gebouwen API
  version: 1.0.0
servers:
  - url: https://api.voorbeeld.example/v1
paths:
  /getGebouwen/:
    get:
      operationId: getGebouwen
      parameters:
        - name: pand_id
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Lijst van gebouwen
          content:
            application/json:
              schema:
                type: object

De commando's om te linten:

npm install -g @stoplight/spectral-cli
curl -sL https://gitdocumentatie.logius.nl/publicatie/api/adr/2.2.0/media/linter.yaml > linter.yaml
spectral lint -r linter.yaml api-fout.yaml
spectral lint -r linter.yaml api-goed.yaml

De uitvoer voor api-fout.yaml, met de paden ingekort, en exitcode 1:

  2:6   error  info-contact                 Info object must have "contact" object.
  8:17  error  nlgov:paths-kebab-case       /getGebouwen/ is not kebab-case.
  8:17  error  path-keys-no-trailing-slash  Path must not end with slash.
 12:17  error  nlgov:query-keys-camel-case  pand_id is not lower camelCase.
 16:17  error  nlgov:problem-invalid-input  GET and DELETE endpoints that have parameters, and all other endpoints must be able to return a 400 response
 17:15  error  nlgov:missing-header         Return the full version number in a response header.

✖ 6 problems (6 errors, 0 warnings, 0 infos, 0 hints)

De zes meldingen komen overeen met de regels /core/doc-openapi-contact, /core/path-segments-kebab-case, /core/no-trailing-slash, /core/query-keys-camel-case, /core/error-handling/invalid-input en /core/version-header.

Het gecorrigeerde bestand hieronder gaf No results with a severity of 'error' found! en exitcode 0. De naam pandId, het pad /gebouwen, de API-Version-header, het contactblok en de problem-respons met status, title en detail zijn de aanpassingen. De gegevens zijn fictief.

openapi: 3.0.3
info:
  title: Gebouwen API
  description: Fictief voorbeeld van een API voor gebouwen.
  version: 1.0.0
  contact:
    name: Team Geo
    url: https://www.voorbeeld.example/contact
    email: geo@voorbeeld.example
servers:
  - url: https://api.voorbeeld.example/v1
paths:
  /gebouwen:
    get:
      operationId: listGebouwen
      summary: Lijst van gebouwen
      parameters:
        - name: pandId
          in: query
          description: Filter op pandidentificatie.
          schema:
            type: string
      responses:
        '200':
          description: Lijst van gebouwen
          headers:
            API-Version:
              description: Volledig versienummer van de API.
              schema:
                type: string
                example: 1.0.0
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Ongeldige invoer
          headers:
            API-Version:
              description: Volledig versienummer van de API.
              schema:
                type: string
                example: 1.0.0
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                  title:
                    type: string
                  detail:
                    type: string

Het bestand toetst alleen of de beschrijving klopt, niet of de draaiende API zich eraan houdt. De publicatie noemt zelf per regel hoe te testen, en de regel over het publiceren van het OpenAPI-bestand eist bovendien dat het document zonder authenticatie en met CORS te downloaden is. Een draaiende API controleert u dus ook met een echt verzoek, bijvoorbeeld een controle op de 404 bij een slash.

Naast de kern kent ADR 2.2.0 drie normatieve modules: Geospatial, Signing en Encryption. De kernregel /core/modules/geospatial zegt: "The API Design Rules Module: Geospatial version 1.0.x MUST be applied when providing geospatial data or functionality." Signing en Encryption gelden alleen als u payloads ondertekent of versleutelt; de regels zelf verplichten dat niet. De transportregels (TLS, security headers en CORS) staan in versie 2.2.0 als technische regels in de kern, onder /core/transport/….

Voor geodata is de Geospatial-module het belangrijkst. Ze schrijft GeoJSON voor in verzoeken en antwoorden, CRS84 als standaardstelsel "in line with OGC API Features Requirement 10", een Content-Crs-header in het antwoord en, als het nodig is, ETRS89 of RD (regel /geo/preferred-crs). Dat sluit aan op deel 2 van OGC API Features; een uitgewerkt voorbeeld met crs en Content-Crs staat op WFS en OGC API Features. De Spectral-ruleset uit bijlage A toetst de kernregels, niet deze module.

• Het vaste adres wijst naar een oudere versie. Het adres static.developer.overheid.nl/adr/ruleset.yaml, dat de publicatie zelf in de installatie-instructie noemt, verwees op 11 oktober 2026 via een HTTP 301 naar het linter.yaml van versie 2.1.0. Dat bestand gaf andere meldingen dan dat van 2.2.0: het weigerde een OpenAPI 3.1-bestand ("Use OpenAPI Specification for documentation") en eiste een resource /openapi.json. Pin daarom het bestand uit de versiemap in uw CI.
• Waarschuwingen en fouten. De linter geeft exitcode 1 bij fouten. Waarschuwingen blokkeren niet, dus bepaal of u ze streng wilt behandelen.
• Alleen de technische regels. Functionele regels, zoals zelfstandige naamwoorden voor resources of een afwegingsnotitie bij een afwijking, kan geen linter beoordelen.
• Nederlandse veldnamen. De regel /core/interface-language vraagt om Nederlandstalige interfaces tenzij er een officieel Engels glossarium bestaat. Een Engelse API-beschrijving kan dus een afweging vragen.
• Geodata. Een groene linter zegt niets over de module Geospatial. Toets CRS84 als standaard en de Content-Crs-header apart, bijvoorbeeld met een echt verzoek.

De standaard geldt voor REST-API's, niet voor elk koppelvlak. SOAP-koppelingen, StUF en Digikoppeling zijn geen REST-koppelvlakken, en OGC-services zoals WMS of WFS hebben eigen specificaties (zie WMS en WMTS). Omdat de standaard het gebruik van REST niet verplicht, is er geen plicht om een bestaande SOAP-koppeling te vervangen. Voor nieuwe REST-API's van een overheid geldt de standaard wel, tenzij u een afwijking motiveert. Een leveranciersmatige keuze voor het bouwen van zo'n API behandelt maatwerk software; over de afhankelijkheid van een leverancier gaat vendor lock-in en exitstrategie.