developer.overheid.nl

Ontwikkelaarsportaal van de Nederlandse overheid

Ga naar hoofdinhoud

API Architectuur

Dit is een samenvatting van de Architectuur van de NL API Strategie van het Kennisplatform API's

Het volledige Architectuurdocument is vastgesteld en online gepubliceerd als onderdeel van het Kennisplatform API's.

Introductie​

Dit architectuurdocument is onderdeel van de NL API Strategie en biedt een verdieping op de algemene inleiding. De versie is opgesteld in december 2023 en is los gepositioneerd ten opzichte van de eerdere geïntegreerde versie.

De NL API Strategie is opgebouwd uit drie hoofdcomponenten

  • Algemene documenten (Inleiding, Architectuur, Gebruikerswensen)
  • Normatieve standaarden (zoals API Design Rules, OAS, NL GOV OAuth‑profiel, Digikoppeling REST API)
  • Functionele/technische modules (bijvoorbeeld Geospatial, Transport Security, Access Control, Hypermedia)

Het hoofdstuk Architectuur beschrijft de rol van deze componenten binnen het bredere strategisch kader en de belangrijkste delen zijn hier samengevat

Typologie van API’s​

Binnen de NL API Strategie wordt een onderscheid gemaakt in verschillende soorten API’s, afhankelijk van hun rol binnen een informatieketen of applicatielandschap:

Type APIBeschrijving
System APIDirecte toegang tot een specifieke databron of systeem. Beperkt in logica.
Process APICombineert meerdere System API’s en bevat domeinlogica (ook wel: orchestration).
Experience APIOp maat gemaakte API voor specifieke afnemers of kanalen.
Public APIAPI’s die publiek beschikbaar zijn voor derden, vaak met toegangsbeheer.
Private APIAlleen intern gebruikt, niet bedoeld voor externe partijen.

Deze typologie helpt bij het structureren van API-landschappen en het toewijzen van verantwoordelijkheden in grotere overheidsorganisaties. Een veelgebruikt voorbeeld is de Common Ground-architectuur waarbij System API’s toegang geven tot bronnen als BAG of BRK, en Process API’s dienstlogica bevatten voor bijvoorbeeld Zaakgericht Werken (ZGW API's).

Verder lezen

API Capability Model​

Het API Capability Model beschrijft modulair de functionaliteiten die samenhangen met de inzet van API's. De opbouw helpt organisaties bij het prioriteren van ontwikkelinspanningen en bij het toetsen van bestaande API’s. Het model bestaat uit de volgende onderdelen:

  • Registratie & Gebruik
    • Aanmelden & Registratie: Zelf-service onboarding van ontwikkelaars en hun applicaties inclusief registratie, credential issuance, client registration en beheer. 
    • Ontdekken: Zorgt voor vindbaarheid via portals, catalogi en API directories (zoals het Developer Overheid API Register ).
  • Realisatie & Beheer
    • Realisatie: Behelst ontwerp, ontwikkeling, testen en het technisch beschikbaar maken van APIs.
    • API Governance: Beleidsregels, standaarden, naming conventions en richtlijnen om uniformiteit te garanderen.
    • API Lifecycle beheer: Proces van aanbieden, versiebeheer, deprecatie, sunset-fases en communicatie richting gebruikers.
    • Platform beheer: Operationeel beheer van de API Gateway, sleutelmanagement, toegangsmatrix en beheer van tooling.  
  • Verkeersstroom beheer
    • Mediatie & Orkestratie: Routing, validatie, datatransformaties en foutafhandeling tussen client en backend systemen.
    • Telemetrie & Inzicht: Logging, monitoring, dashboards en analytics voor gebruiksinzicht en platformgezondheid.
    • Service level beheer: SLA’s, throttling, rate limits, doorbelasting en capaciteitsbeheer.
    • Beveiliging: Identificatie (authenticatie), autorisatie, sleutelbeheer, policy enforcement, audit logging en anomalie detectie. 

API Capability model

Verder lezen

API management functionaliteit​

In een volwassen API-architectuur is API-management onmisbaar voor het goed kunnen beheren, beveiligen en monitoren van API’s. Het hoofdstuk API-management-functionaliteit uit de architectuurdocumentatie van de NL API Strategie beschrijft de belangrijkste functies en hun positionering.

Belangrijkste API-managementfuncties​

FunctionaliteitBeschrijving
API GatewayCentrale toegangspoort voor inkomend verkeer. Zorgt voor policy enforcement, routing, throttling, caching, request logging en validatie.
Developer PortalPublicatiepunt voor discovery, documentatie en registratie van API-gebruikers. Biedt self-service toegang voor developers.
BeveiligingsservicesOndersteuning van authenticatie (zoals OAuth2, mTLS), autorisatie (rollen/scopes) en beveiligingsbeleid.
Monitoring en AnalyticsDashboarding en alerts voor gebruik, beschikbaarheid, fouten en performance. Helpt bij SLA-bewaking en verbeteringen.
Rate limiting & QuotasBeschermen van achterliggende systemen tegen overbelasting door limieten op te leggen aan gebruik per client.
Lifecycle managementVersiebeheer, deprecatiebeleid en ondersteuning voor staging (dev, test, prod) om API-evolutie beheerst uit te voeren.

Architectonische inbedding​

De functionaliteiten kunnen beperkt gecentraliseerd worden aangeboden (bijvoorbeeld via een generiek API-platform binnen een overheidsorganisatie) maar zullen hoofdzakelijk decentraal per API-team worden ingericht conform het Federatief Data Stelsel (FDS). Afstemming over design, logging, beveiliging en lifecycle management blijft essentieel bij decentrale implementaties.

De API-architectuur benadrukt dat API-management niet alleen een technische aangelegenheid is, maar ook organisatorische en governance vraagstukken omvat. Denk aan:

  • Wie bepaalt welke API’s beschikbaar worden gesteld?
  • Hoe wordt versiebeheer uitgevoerd?
  • Wat zijn de voorwaarden voor toegang en gebruik?
  • Voldoen de API's aan de wetten, regels en standaarden die we hebben afgesproken?

Tot slot​

Het gebruik van open source API-management tooling (zoals APISIX, WSO2, KONG, TYK of andere open source alternatieven) wordt aanbevolen mits deze passen binnen de Nederlandse open-standaardenstrategie.

Door het toepassen van een duidelijke typologie en het Capability Model wordt het eenvoudiger om API’s in te richten binnen de bredere API-strategie van de overheid. Dit sluit aan bij het streven naar een API-first benadering en modulaire overheidsinfrastructuur.

Meer informatie​