CONCEPT — Let op: Deze skill is geen officieel product van Logius. De beschrijvingen zijn informatieve samenvattingen — niet de officiële standaarden zelf. De definities op forumstandaardisatie.nl en Logius zijn altijd leidend. Overheidsorganisaties die generatieve AI inzetten dienen te voldoen aan het Overheidsbreed standpunt voor de inzet van generatieve AI. Zie DISCLAIMER.md en onze verantwoording.
API Design Rules (NL GOV)
Agent-instructie: Deze skill helpt bij het implementeren van APIs conform de NL GOV API Design Rules. Gebruik de Spectral linter om OpenAPI specs te valideren. De regels zijn verplicht onder 'pas-toe-of-leg-uit' van het Forum Standaardisatie.
De API Design Rules (ADR) zijn de Nederlandse standaard voor het ontwerpen van RESTful APIs bij de overheid. Ze zijn verplicht onder het "pas-toe-of-leg-uit" regime van het Forum Standaardisatie. De standaard bevat concrete, toetsbare regels voor URI-ontwerp, HTTP-methoden, versiebeheer, beveiliging, foutafhandeling en meer.
Versiemodel
De ADR kent twee publicatiekanalen (vergelijkbaar met W3C-standaarden):
- Vastgestelde versie (DEF): de officieel goedgekeurde versie, gepubliceerd op
gitdocumentatie.logius.nl - Werkversie (draft): de ontwikkeling richting de volgende release, gepubliceerd op
logius-standaarden.github.io. De werkversie op GitHub Pages is de lopende ontwikkeling richting de volgende release. De ReSpec-configuratie toont daar nog '2.1.0' maar dit betreft werk-in-uitvoering.
Modules hebben geen eigen vaststellingsproces — ze ontlenen hun status aan de standaard die ernaar verwijst. Als de ADR in een vastgestelde versie normatief naar een module verwijst, is die module daarmee ook vastgesteld. Zo is de Geospatial module v1.0.x normatief onderdeel van ADR v2.1.0 en daarmee vastgesteld. De inhoud van Transport Security is in ADR v2.1.0 ingebed als sectie 3.8 met eigen regels (/core/transport/*). De module v1.0 staat nog normatief vermeld in de leeswijzer van v2.1.0, maar de GitHub-repository is gearchiveerd.
Repositories
| Repository | Beschrijving | Licentie | Vastgesteld | Draft |
|---|---|---|---|---|
| API-Design-Rules | Hoofdspecificatie (ADR) | CC-BY-4.0 | v2.1.0 | Draft |
| ADR-Beheermodel | Beheermodel voor de ADR standaard — gearchiveerd, vervangen door API-Standaarden-Beheermodel | CC-BY-4.0 | v1.0 | - |
| API-Standaarden-Beheermodel | Overkoepelend beheermodel API-standaarden | CC-BY-4.0 | - | Draft |
| API-mod-geospatial | Module: Geospatial (GeoJSON, CRS) — normatief in ADR v2.1.0 | CC-BY-4.0 | v1.0.3 | Draft |
| API-mod-transport-security | Module: Transport Security — gearchiveerd; inhoud ingebed in ADR v2.1.0; normatief vermeld in leeswijzer; repo gearchiveerd | CC-BY-4.0 | - | - |
| API-mod-signing | Module: HTTP Message Signing — draft | CC-BY-4.0 | - | Draft |
| API-mod-encryption | Module: Encryption (JWE) — draft | CC-BY-4.0 | - | Draft |
| api-linter-impactanalyse | Python tool: test Spectral regels tegen echte OpenAPI specs uit het API-register | Niet gespecificeerd | - | - |
| zaakgericht-werken-api | API-specificatie voor zaakgericht werken | CC-BY-4.0 | - | - |
Technische Regels
URI-ontwerp
- Gebruik kebab-case voor padsegmenten:
/mijn-documenten(niet/mijnDocumenten) - Gebruik camelCase voor query-parameters:
?sortOrder=desc - Geen trailing slashes:
/api/v1/users(niet/api/v1/users/) - Geen bestandsextensies (gebruik Accept-header voor content negotiation)
- Major versie in URI:
/v1/resources(Let op: in de OAS moet dit op serverniveau worden gespecificeerd, niet in individuele paden. Dit om uit te sluiten dat één API meerdere major versies in verschillende paden heeft, wat verwarrend is. De linter controleert op aanwezigheid van major versie in server URL, niet in individuele paden.) - Operaties als sub-resources: laatste padsegment mag starten met
_(bijv./_search) - Geen gevoelige informatie in URIs (niet beschermd door TLS)
HTTP-methoden
| Methode | Gebruik | Veilig | Idempotent |
|---|---|---|---|
| GET | Resource ophalen, nooit wijzigen | Ja | Ja |
| POST | Subresource aanmaken in collectie | Nee | Nee |
| PUT | Resource aanmaken of volledig vervangen | Nee | Ja |
| PATCH | Gedeeltelijke update | Nee | Nee |
| DELETE | Resource verwijderen | Nee | Ja |
Versiebeheer
- Major versie in URI-pad:
/v1,/v2 - Volledige versie in
API-Versionresponse header:1.2.3 - Semantic versioning (major.minor.patch) in
info.version - Deprecation schedule publiceren bij major version changes
- Vaste transitieperiode tussen major versies
Foutafhandeling
Gebruik application/problem+json (RFC 9457) voor foutresponses:
{
"type": "https://example.com/errors/insufficient-funds",
"title": "Insufficient Funds",
"status": 422,
"detail": "Your current balance is 30, but that costs 50.",
"instance": "/account/12345/transactions/abc"
}
Geen technische details (stack traces, interne hints) in foutmeldingen.
Datum en tijd
- Gebruik RFC 3339 formaat voor datum/tijd waarden
- Altijd een timezone specificeren bij
date-timevelden (bijv.2026-04-11T10:30:00+02:00) - Gebruik
format: datewanneer alleen een datum nodig is (nietdate-time) - Specificeer altijd een
formatvoor properties die datum of tijd bevatten - De Spectral linter bevat 4 regels die dit afdwingen (
date-time-ensure-timezone,specify-format-for-date-and-time,time-without-timezone,use-date-instead-of-datetime)
Naamgeving
- Resources als zelfstandige naamwoorden (niet werkwoorden)
- Meervoud voor collecties:
/users,/orders - Enkelvoud voor individuele resources:
/users/{id} - Definieer interfaces in het Nederlands tenzij er een officieel Engelstalig begrippenkader bestaat
- Verberg implementatiedetails (geen framework- of databasenamen)
OpenAPI Documentatie
- OpenAPI 3.0+ specificatie verplicht
- Publiceer JSON op standaardlocatie:
/openapi.json(VERPLICHT); YAML (/openapi.yaml) is OPTIONEEL - Contactinformatie (
info.contactmetname,email,url) wordt sterk aanbevolen voor publieke APIs (ADR/core/doc-openapi-contact: SHOULD); de Spectral linter dwingt deze velden af als error voor publieke APIs - CORS ondersteunen voor documentatie-toegang
Modules
Transport Security (TLS)
Let op: De Transport Security module werd als aparte module normatief verwezen door ADR v2.0.0. Vanaf ADR v2.1.0 zijn de transport-security-eisen ingebed in de hoofdspecificatie (sectie 3.8, regels
/core/transport/*) en is de repository gearchiveerd. De module v1.0 staat nog normatief vermeld in de leeswijzer van ADR v2.1.0.
Alle verbindingen MOETEN TLS gebruiken (wettelijk verplicht). Volg de laatste NCSC-richtlijnen.
Verplichte security headers in alle API-responses:
| Header | Doel |
|---|---|
Cache-Control: no-store |
Voorkom caching van gevoelige data |
Content-Security-Policy: frame-ancestors 'none' |
Clickjacking bescherming |
Content-Type: application/json |
Specificeer content type |
Strict-Transport-Security |
Vereis HTTPS |
X-Content-Type-Options: nosniff |
Voorkom MIME sniffing |
X-Frame-Options: DENY |
Clickjacking bescherming |
Access-Control-Allow-Origin |
CORS beleid |
Geospatial Module (v1.0.3 — vastgesteld)
Normatief onderdeel van ADR v2.1.0. Verplicht bij geospatiale data. Regelt GeoJSON encodering, bounding box filtering, en coördinaatsystemen (CRS). Zie de vastgestelde versie.
Signing Module (JAdES) — draft
Let op: Deze module is nog in concept (draft) en is nog niet goedgekeurd door het Technisch Overleg. De inhoud kan nog wijzigen.
Voor end-to-end berichtintegriteit en authenticiteit. Gebruikt JAdES detached signatures met RSASSA-PSS (PS256), minimaal 256 bits. Signatures in Payload-Signature en Message-Signature HTTP headers. OpenAPI representatie met format: jws-compact-detached.
Encryption Module (JWE) — draft
Let op: Deze module is nog in concept (draft) en is nog niet goedgekeurd door het Technisch Overleg. De inhoud kan nog wijzigen.
Voor end-to-end versleuteling van request/response payloads wanneer transport-level encryptie niet voldoende is (bijv. bij niet-vertrouwde intermediairs).
Implementatievoorbeeld
Python/FastAPI
from fastapi import FastAPI, Query, Request, HTTPException
from fastapi.responses import JSONResponse
from pydantic import BaseModel
from datetime import date
app = FastAPI(
openapi_url="/v1/openapi.json",
title="Zaakgericht Werken API",
version="1.2.0",
contact={"name": "API Team", "url": "https://example.com/support", "email": "api@example.com"},
servers=[{"url": "https://api.example.com"}],
)
class Zaak(BaseModel):
id: str
zaaktype: str
omschrijving: str
startdatum: date
status: str
@app.middleware("http")
async def add_adr_headers(request: Request, call_next):
response = await call_next(request)
response.headers["API-Version"] = "1.2.0"
response.headers["Content-Type"] = "application/json"
response.headers["Cache-Control"] = "no-store"
response.headers["Strict-Transport-Security"] = "max-age=31536000"
response.headers["X-Content-Type-Options"] = "nosniff"
response.headers["X-Frame-Options"] = "DENY"
response.headers["Content-Security-Policy"] = "frame-ancestors 'none'"
return response
@app.get("/v1/zaken", response_model=list[Zaak])
async def list_zaken(
status: str | None = Query(None, description="Filter op status"),
startdatum__gte: date | None = Query(None, alias="startdatumGte", description="Vanaf datum"),
page: int = Query(1, ge=1),
page_size: int = Query(20, ge=1, le=100, alias="pageSize"),
):
"""Haal zaken op met paginering en filtering (ADR-compliant)."""
# Paginering met standaard page_size=20, max 100
offset = (page - 1) * page_size
return db.query_zaken(status=status, since=startdatum__gte, offset=offset, limit=page_size)
@app.exception_handler(HTTPException)
async def problem_json_handler(request: Request, exc: HTTPException):
"""RFC 9457 problem+json (verplicht per ADR)."""
return JSONResponse(
status_code=exc.status_code,
content={
"type": f"https://api.example.com/errors/{exc.status_code}",
"title": exc.detail if isinstance(exc.detail, str) else "Error",
"status": exc.status_code,
"instance": str(request.url),
},
media_type="application/problem+json",
)
Implementatie Checklist
- OpenAPI 3.0+ spec op
/openapi.json(VERPLICHT);/openapi.yamlis optioneel - Contactinformatie in spec
- Major versie in URI-pad (
/v1) - Volledige versie in
API-Versionresponse header - Semantic versioning in
info.version - Kebab-case paden, camelCase query-parameters
- Geen trailing slashes
- Verplichte security headers
- TLS op alle verbindingen
-
application/problem+jsonvoor foutresponses - Geen gevoelige data in URIs
- CORS geconfigureerd
Spectral Linter
De Spectral linter valideert OpenAPI specs tegen ADR regels. De DON-hosted ruleset bevat 11 regels; de GitHub-versie bevat 22 regels (inclusief extra checks voor datum/tijd, naamgeving en foutafhandeling).
# Optie 1: Publieke DON-hosted ruleset (geen GitHub auth nodig, aanbevolen)
npx @stoplight/spectral-cli lint <jouw-spec.yaml> \
--ruleset https://static.developer.overheid.nl/adr/ruleset.yaml
# Optie 2: Ruleset ophalen via GitHub API
gh api repos/logius-standaarden/API-Design-Rules/contents/media/linter.yaml \
-H "Accept: application/vnd.github.raw" > /tmp/adr-linter.yaml
npx @stoplight/spectral-cli lint <jouw-spec.yaml> --ruleset /tmp/adr-linter.yaml
# Bekijk beschikbare regels (DON-versie)
curl -s https://static.developer.overheid.nl/adr/ruleset.yaml | grep -oE "^\s{2}\S+:" | sed 's/^\s*//;s/:$//'
# Linter testcases bekijken
gh api repos/logius-standaarden/API-Design-Rules/contents/linter/testcases --jq '.[].name'
Belangrijke Spectral regels (DON-naam / GitHub-naam):
include-major-version-in-uri/nlgov:include-major-version-in-uri- Major versie in URI padpaths-no-trailing-slash/nlgov:paths-no-trailing-slash- Geen trailing slashespaths-kebab-case/nlgov:paths-kebab-case- Kebab-case padsegmentenhttp-methods/nlgov:http-methods- Alleen standaard HTTP methodenmissing-version-header/nlgov:missing-version-header- Version header in 2xx/3xx responsesuse-problem-schema/nlgov:use-problem-schema- Problem+json voor fouten
Alleen in de GitHub-versie (22 regels totaal, 11 extra t.o.v. DON):
nlgov:query-keys-camel-case- camelCase query parametersnlgov:info-contact-fields-exist- Contactinformatie velden aanweziginfo-contact- Contactobject aanwezig (zondernlgov:prefix)nlgov:semver- Semantic versioning formaatnlgov:openapi-root-exists- OpenAPI root object aanwezigoas3-api-servers- Servers array aanwezig (built-in regel op error gezet)nlgov:problem-schema-members- Verplichte velden in problem+json schema (RFC 9457)nlgov:date-time-ensure-timezone- Datum/tijd velden met timezonenlgov:time-without-timezone- Detecteerttimeformat zonder timezonenlgov:specify-format-for-date-and-time- Verplicht format voor datum/tijd propertiesnlgov:use-date-instead-of-datetime- Gebruikdatei.p.v.date-timewaar geen tijd nodig is
Achtergrondinfo
Zie reference.md voor Express.js/Go voorbeelden, impact analyse tool, en repo-exploratie commando's. Zie conflicts.md voor bekende discrepanties tussen GitHub-tags en gepubliceerde versies.