Hoe te voldoen
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: dit zijn niet álle API Design Rules. Kijk voor een volledig overzicht van de regels in de repository van de standaard op https://gitdocumentatie.logius.nl/publicatie/api/adr/.
/core/doc-openapi-contact
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.
/core/doc-openapi
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.
/core/http-methods
Deze regel schrijft voor dat alleen de standaard HTTP methods GET, POST, PATCH, PUT, DELETE, HEAD, TRACE en OPTIONS toegestaan zijn.
/core/no-trailing-slash
Deze regel schrijft voor dat een path geen trailing slash mag bevatten, met uitzondering van de root.
/core/publish-openapi
Deze regel schrijft voor dat elke api een /openapi.json file moet publiceren zodat tooling hier gebruik van kan maken.
/core/semver
Deze regel schrijft voor dat versionering van API's via Semantic Versioning (major.minor.patch formaat) moet geschieden.
/core/uri-version
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.
/core/version-header
Deze regel schrijft voor dat iedere API response een API-Version response header moet bevatten met daarin het volledige versienummer van de API.