Handreiking API Design Rules

Algemeen

Beheerder: Logius

Status bij Forum Standaardisatie: pas toe, leg uit

Waarde van de standaard

De NLGov REST API Design Rules (vanaf hier kortweg: API Design Rules) is een verzameling richtlijnen om de beschrijving, structuur en het gedrag van RESTful API’s te standaardiseren.

Belangrijke voordelen van de API Design Rules zijn:

Standaardiseren van de uitwisseling van gegevens, zodat de interoperabiliteit tussen (overheids)organisaties wordt verhoogd.
Meer gestandaardiseerde API’s en API beschrijvingen, zodat ontwikkelaars deze API’s sneller begrijpen en kunnen gebruiken in hun eigen context.
Betere kwaliteit van API’s, zodat er minder fouten, tekortkomingen en andersoortige issues optreden bij hun daadwerkelijk gebruik.
Hogere veiligheid van API’s, zodat er minder veiligheidsrisico’s ontstaan.

De API Design Rules bieden waarde aan de volgende specifieke doelgroepen:

Doelgroep	Waarde
Managers	Hogere interoperabiliteit door het gebruik van gestandaardiseerde vormen van gegevensuitwisseling. Lagere kans op verstoringen bij het aanbieden van API’s, doordat het volgen van de richtlijnen belangrijke risico’s mitigeert.
Managers	Verhogen van het vertrouwen in de betrouwbaarheid van informatieproducten, doordat meer inzicht is in hun totstandkoming.
Ontwikkelaars	Sneller kunnen gebruiken van API’s van andere organisaties, doordat deze API’s en hun beschrijving meer gestandaardiseerd zijn en doordat automatisch clients kunnen worden gegenereerd op basis van de API beschrijving.
Security officers	Een lagere kans op security incidenten, doordat het volgen van de richtlijnen een aantal beveiligingsrisico’s mitigeert.

Werking van de standaard

De API Design Rules zijn onderdeel van de Nederlandse API strategie. Deze strategie bevat een verzameling van documenten, waarvan een deel ook onderdeel zijn van de pas toe, leg uit lijst van Forum Standaardisatie. Naast de API Design Rules geldt dat bijvoorbeeld ook voor de Nederlandse profielen op OAuth, OpenID Connect en een module voor geografische gegevens. Deze documenten zijn totstand gekomen in het Kennisplatform API’s; een community van ontwikkelaars met een liefde voor API’s.

De API Design Rules bevatten functionele en technische richtlijnen. De functionele richtlijnen gaan bijvoorbeeld over de naamgeving van resources, het conformeren aan HTTP conventies, het omgaan met wijzigingen en het algemene gedrag van API’s. De technische richtlijnen hebben bijvoorbeeld betrekking op het gebruik van de Open API Specification, versionering en een betere beveiliging door het gebruik van TLS, CORS en beveiligingsheaders.

Relatie met GDI domeinarchitectuur gegevensuitwisseling

De API Design Rules geven een invulling aan de volgende principes in de domeinarchitectuur.

Principe	Invulling
Gegevens die kunnen worden gedeeld zijn vindbaar, toegankelijk, interoperabel en herbruikbaar	De standaard zorgt ervoor dat gegevens benaderbaar zijn via standaard, open en algemeen implementeerbare protocollen en dat hun datamodel is beschreven.
Metagegevens zijn begrijpelijk voor mensen	De standaard maakt het mogelijk om functionele beschrijvingen toe te voegen aan de operaties en gegevenselementen van API’s.
Gegevens worden geleverd vanuit herbruikbare gegevensdiensten	Het gebruik van de standaard is een implicatie van dit principe.
Gegevens worden zo vroeg mogelijk gevalideerd	De standaard maakt het mogelijk om ontvangen gegevens te valideren op basis van het datamodel dat zou moeten zijn beschreven bij API’s.

De standaard is ondersteunend aan de volgende functies in het functiemodel van de domeinarchitectuur:

Beheren informatie- en gegevensmodellen
Beheren metagegevens over gegevensdiensten
Beschikbaar stellen metagegevens
Ontwikkelen en beheren gegevensdiensten
Valideren gegevens

Positionering van de standaard

Andere vormen van API's

De standaard is specifiek gericht op API’s die voldoen aan het REST principe. REST staat voor Representational State Transfer en gaat ervan uit dat API’s toestandsloos zijn, verwijzen naar resources en gebruik maken van de standaard HTTP operaties. Er zijn echter ook andere vormen van API’s, zoals HTTP-gebaseerde API’s die niet RESTful zijn of die gebruik maken van standaarden zoals GraphQL, gRPC of SPARQL. Een deel van de richtlijnen zijn wel toepasbaar op deze andere vormen van API’s. Dat is echter niet expliciet gemaakt in de standaard.

Impact van de standaard

De API Design Rules is een relatief overzichtelijk geheel, met het idee dat ze daarom relatief eenvoudig toe te passen zouden moeten zijn door ontwikkelaars. Ze bevatten ook voorbeelden om toepassing te vereenvoudigen.

De API Design Rules stellen het gebruik van de OpenAPI Specification verplicht voor het documenteren van API’s. Hierdoor kunnen een verscheidenheid aan tools worden gebruikt om de documentatie weer te geven (bijv. Swagger UI of ReDoc) of taken zoals testen of codegeneratie te automatiseren. Deze tools maken het gebruik dus eenvoudiger.

Op developer.overheid.nl zijn ook een aantal tools beschikbaar om het gebruik van de API Design Rules te vereenvoudigen. De ADR Linter controleert of een OpenAPI Specification document compliant is met de API Design Rules. De laatste heeft ook kennis van meerdere versies van de ADR. De OAS Generator genereert een basisvulling voor een OpenAPI Specification document op basis van minimale configuratie.

Organisaties zullen er zelf voor moeten zorgen dat hun ontwikkelaars zich bewust zijn van deze standaard en dat er wordt toegezien op het gebruik van de standaard. Het voldoen aan de richtlijnen zou onderdeel moeten zijn van het testproces en de definition of done van ontwikkelteams.

Aandachtspunten

geen

Relatie met andere standaarden

Relatie met OpenAPI Specification

De OpenAPI Specificatie (OAS) definieert een standaard, programmeertaalonafhankelijke interface voor RESTful APIs, waardoor zowel mensen als computers de mogelijkheden van een service kunnen ontdekken en begrijpen zonder toegang tot broncode, documentatie of via het inspecteren van netwerkverkeer. Onderdeel daarvan is het beschrijven van de operaties en de gegevenselementen van de API. Daarmee kan ook het technisch datamodel worden vastgelegd conform de JSON Schema standaard. De API Design Rules stellen dat het beschikbaar stellen van een dergelijke specificatie verplicht is voor API’s.

Op deze pagina