developer.overheid.nl

Ontwikkelaarsportaal van de Nederlandse overheid

Ga naar hoofdinhoud

18 artikelen getagd met "API"

Application Programming Interface

Laat alle tags zien

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

ADR Cheat Sheet

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.

ADR Linter

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.

ADR Validator

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:

Bouw een API

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.

Foutmeldingen met Problem Details

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.

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//gitdocumentatie.logius.nl/publicatie/api/adr/.

Maak een OpenAPI specificatie

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.

OAS Generator

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.

OpenAPI Specification (OAS)

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