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 CLI-tool om te valideren of een API zich gedraagt conform deze delen van de NL API Strategie:

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

Hier leggen we uit welke stappen je kunt doorlopen om snel en efficiënt een nieuwe REST API te ontwikkelen. We gaan hierbij uit van een design first aanpak, dus we starten met het API design.

Problem JSON (application/problem+json) is een krachtige standaard voor het verbeteren van de foutafhandeling in API's en het bieden van een betere ervaring voor zowel developers als eindgebruikers.

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/.

Een OpenAPI Specificatie (OAS) is een YAML of JSON bestand met de eigenschappen van de data die een REST API als input accepteert en als output teruggeeft. Een OpenAPI Specificatie beschrijft niet hoe een API geïmplementeerd is, en heeft dus geen binding met specifieke programmeertalen.

Deze tool is enkel bedoeld om je op weg te helpen met het API design, inclusief herbruikbare componenten en best practices van de API Design Rules. Eventuele ontbrekende of foutieve gegevens dienen handmatig toegevoegd of gewijzigd te worden.

Deze standaard is verplicht voor REST API's van de overheid. Let op: momenteel wordt alleen OAS versie 3.0.x goedgekeurd.