Deze regel schrijft voor dat REST API's van de overheid beschreven moeten worden in het OpenAPI Specification formaat. De huidige toegestane versie is 3.0.x.

Deze regel schrijft voor dat je contactinformatie in OAS moet opnemen voor publieke API's. Het API register gebruikt deze informatie onder andere om gebruikers in de gelegenheid te stellen om issues te melden en om aanbieders op de hoogte te brengen van gesignaleerde problemen.

Deze regel schrijft voor dat alleen de standaard HTTP methods GET, POST, PATCH, PUT, DELETE, HEAD, TRACE en OPTIONS toegestaan zijn.

Deze regel schrijft voor dat een path geen trailing slash mag bevatten, met uitzondering van de root.

Deze regel schrijft voor dat elke api een /openapi.json file moet publiceren zodat tooling hier gebruik van kan maken.

Deze regel schrijft voor dat versionering van API's via Semantic Versioning (major.minor.patch formaat) moet geschieden.

Deze regel schrijft voor dat de major versie, voorafgegaan door de letter v, opgenomen moet zijn in de URI van het endpoint. In OAS mag deze niet gespecificeerd worden op path niveau; dit zou impliceren dat er binnen hetzelfde endpoint meerdere (major versies van) API's beschikbaar zijn, terwijl elke API vergezeld moet worden van een eigen /openapi.json.

Deze regel schrijft voor dat iedere API response een API-Version response header moet bevatten met daarin het volledige versienummer van de API.

Het actuele en uitgebreide overzicht van de REST API Design Rules vind je hier: API Design Rules. Hieronder vind je echter een extract met de belangrijkste technische regels en best practices om te gebruiken tijdens het ontwerpen van een API.

De ADR Linter controleert of een OpenAPI Specificatie compliant is met de API Design Rules. De linter is gebaseerd op het Open Source project Spectral.

De API Design Rules (ADR) Validator is een command line interface die gebruikt kan worden om te valideren of een API zicht gedraagt conform deze delen van de NL API Strategie:

Deze standaard is verplicht voor REST API's van de overheid.

Onderstaande technische regels kunnen automatisch gecontroleerd worden met de ADR Linter. Voor deze regels zijn er tips en codevoorbeelden beschikbaar om API's te laten slagen. Let op//gitdocumentatie.logius.nl/publicatie/api/adr/.