From e65e4cc09c5aca814402c15c827a400effea6546 Mon Sep 17 00:00:00 2001 From: Martin van der Plas Date: Thu, 25 Sep 2025 18:00:10 +0200 Subject: [PATCH 1/3] Update architectuur.md Functioneel de orkestratie functie toegevoegd. Verder: - Wat markdown issues gefixed - figuur verwijzingen eenduidig gemaakt - cloudevents genoemd - de API security architectuur uitgebreid met meer verwijzingen naar OAUTH, OIDC, FDS, FTV, FSC - Multi-level Authentication uitgewerkt --- .../Architectuur/architectuur.md | 194 ++++++++++++------ 1 file changed, 135 insertions(+), 59 deletions(-) diff --git a/API-strategie-algemeen/Architectuur/architectuur.md b/API-strategie-algemeen/Architectuur/architectuur.md index e4329677..20a08764 100644 --- a/API-strategie-algemeen/Architectuur/architectuur.md +++ b/API-strategie-algemeen/Architectuur/architectuur.md @@ -13,11 +13,11 @@ Doel van dit hoofdstuk is om een hoog niveau overzicht te geven van relevante on Specifiek voor REST API's is dat deze 'Resource' gericht zijn en een uniforme manier bieden om resources te lezen, wijzigen, toevoegen of verwijderen. -![](https://github.com/Geonovum/KP-APIs/raw/master/media/clip02.png) +![De plaats van API's bij aanbod van diensten](https://github.com/Geonovum/KP-APIs/raw/master/media/clip02.png) -Figuur 1: De plaats van API's bij aanbod en gebruik van (gegevens)diensten; +> Figuur 1: De plaats van API's bij aanbod en gebruik van (gegevens)diensten; -Figuur 1 toont de plaats van API's in de gegevensuitwisseling en relevante onderwerpen in deze context. Bij de Dienst afnemer speelt +Figuur 1 toont de plaats van API's in de gegevensuitwisseling en relevante onderwerpen in deze context. Bij de Dienst afnemer speelt het gebruik van API's, bij de Dienst aanbieder speelt het aanbieden van API's. In dit hoofdstuk wordt specifiek ingegaan op de 'aanbod kant': het onderdeel 'Diensten toegang' in het schema. @@ -27,13 +27,15 @@ In dit hoofdstuk wordt specifiek ingegaan op de 'aanbod kant': het onderdeel 'Di Overheidsorganisaties bieden diensten aan Burgers, Bedrijven en andere Overheidsorganisaties. Onderstaande figuur geeft de dienstverlening middels API's aan de verschillende partijen grafisch weer. -![alt text](https://github.com/Geonovum/KP-APIs/raw/master/overleggen/Werkgroep%20API%20architectuur/uitwerkingen/media/API-arch-v22.png) -Figuur 2: API Diensten voor Burgers, Bedrijven en Overheden +![API Diensten voor Burgers, Bedrijven en Overheden](https://github.com/Geonovum/KP-APIs/raw/master/overleggen/Werkgroep%20API%20architectuur/uitwerkingen/media/API-arch-v22.png) +> Figuur 2: API Diensten voor Burgers, Bedrijven en Overheden -*Toelichting* +Toelichting API koppelvlakken: -- (A) : API Contactoppervlak Overheid naar Burgers en Bedrijven -- (B) : API Contactoppervlak Overheid naar Overheid (bv onderdelen GDI) +- (A) : API Koppelvlak Overheid naar Burgers en Bedrijven +- (B) : API Koppelvlak Overheid naar Overheid (bv onderdelen GDI) + +Toelichting API doelgroepen: - G2C : Government 2 Citizen (Overheid naar Burger) - G2B : Government 2 Business (Overheid naar Bedrijf) @@ -65,47 +67,44 @@ Een organisatie heeft verschillende soorten API's: Een overheidsorganisatie ontsluit zijn diensten naar andere overheidsorganisaties, naar bedrijven/private organisaties en naar burgers. In onderstaande figuur wordt dit visueel weergegeven. -![alt text](https://github.com/Geonovum/KP-APIs/raw/master/overleggen/Werkgroep%20API%20architectuur/uitwerkingen/media/govapi.png) -Figuur 3 : Soorten API's +![Soorten API's](https://github.com/Geonovum/KP-APIs/raw/master/overleggen/Werkgroep%20API%20architectuur/uitwerkingen/media/govapi.png) +> Figuur 3 : Soorten API's -*Afkortingen*: +**Afkortingen**: - G2C : Government 2 Citizen (Overheid naar Burger) - G2B : Government 2 Business (Overheid naar Bedrijf) - G2G : Government 2 Government (Overheid naar Overheid) -### Systeem, Proces, Convenience ### +### Systeem, Proces, Convenience Deze indeling maakt onderscheid in Systeem, Proces, Convenience API's: - System API (werkt op het niveau van de databron); -- Process API (doet aan orchestration door één of meerdere System API's aan te roepen); +- Process API (doet aan orkestratie door één of meerdere System API's aan te roepen); - Convenience of Experience API (beantwoord één specifieke gebruikersvraag); -### Business / Exposure ### +### Business / Exposure Deze indeling maakt onderscheid in Business en Exposure API's: **Business API definitie:** -Een API die beschreven is in business termen , gebruik maakt van generieke modellen en welke bedrijfsprocessen ondersteund. (Hierbij wordt vermeden om terminology en payloads te gebruiken die specifiek zijn voor 3rd party software om afhankelijkheid van specifieke infrastructuur te voorkomen en te focussen op bedrijfsdoelstellingen; +- Een API die beschreven is in business termen , gebruik maakt van generieke modellen en welke bedrijfsprocessen ondersteund. (Hierbij wordt vermeden om terminology en payloads te gebruiken die specifiek zijn voor 3rd party software om afhankelijkheid van specifieke infrastructuur te voorkomen en te focussen op bedrijfsdoelstellingen; -(Bijvoorbeeld API’s gebaseerd op de Generieke Functies (capabilities) van de Nederlandse Overheid, zie https://www.noraonline.nl/wiki/Generieke_functies, en op de capabilities van de eigen organisatie). +(Bijvoorbeeld API’s gebaseerd op de Generieke Functies (capabilities) van de Nederlandse Overheid, zie [de generieke functies van noraonline.nl](https://www.noraonline.nl/wiki/Generieke_functies), en op de capabilities van de eigen organisatie). -**Exposure API** +**Exposure API**: -Een API die toegang geeft tot de (basis)functionaliteit en data van een (specifiek) systeem. +- Een API die toegang geeft tot de (basis)functionaliteit en data van een (specifiek) systeem. ### Philosophy, Protocol, Encoding Deze indeling gaat uit van de technische aspecten van de API: -- Design Philosophy -(eg RESTful, GraphQL) -- Communications Protocol -(eg HTTP, Websockets) -- Encoding -(eg JSON, Protobuf (binary)) +- Design Philosophy (eg RESTful, GraphQL, Event Driven, Orkestratie) +- Communications Protocol (eg HTTP, Websockets) +- Encoding (eg JSON, Cloudevents, Protobuf (binary)) ### API Virtualisatie @@ -118,7 +117,8 @@ In onderstaand voorbeeld is dit: - Met toegangsbeperking - Met doelbinding -![](https://github.com/Geonovum/KP-APIs/raw/master/overleggen/Werkgroep%20API%20architectuur/uitwerkingen/media/api-virt.png) +![Virtuele varianten van een API](https://github.com/Geonovum/KP-APIs/raw/master/overleggen/Werkgroep%20API%20architectuur/uitwerkingen/media/api-virt.png) +> Figuur 4 : Virtuele varianten van een API ### API Language styles @@ -128,7 +128,7 @@ Onderstaande indeling gaat uit van de bij de API toegepaste 'language' style. - Resource Style: OpenAPI/Swagger, RAML, API Blueprint - Hypermedia Style: HAL, Siren, Atom, HATEOAS - Query Style: GraphQL, OData, SPARQL -- Event-based Style: MQ, WebSub, MQTT, XMPP, AMQP, Kafka, AsyncAPI +- Event-based Style: Cloudevents, MQ, WebSub, MQTT, XMPP, AMQP, Kafka, AsyncAPI ## API Capability Model @@ -137,6 +137,7 @@ Om als organisatie API's aan te bieden aan andere partijen op een gecontroleerde Het onderstaande API Capability model geeft weer aan welke onderwerpen men aandacht moet schenken bij het inrichten van API gedreven dienstverlening. De onderwerpen zijn gegroepeerd in de categorieën *Registratie & gebruik*, *Realisatie & beheer* en *Verkeersstroom beheer*. ![API Capability Model](https://github.com/Geonovum/KP-APIs/raw/master/media/API-Capability.png) +> Figuur 5 : API Capability Model ### Registratie & Gebruik @@ -145,7 +146,7 @@ Deze categorie bevat capabilities voor het ondersteunen van ontwikkelaars die ge - *Aanmelden & Registratie*: functionaliteiten waarmee nieuwe gebruikers zichzelf en hun applicaties kunnen registreren om gebruik te maken van aangeboden API's; - *Ontdekken*: functionaliteiten waarmee gebruikers kennis over aangeboden API's op kunnen doen en delen. -Over het algemeen biedt een API leverancier capabilities ten behoeve van API gebruik in een ontwikkelaarsportaal. +Over het algemeen biedt een API leverancier capabilities ten behoeve van API gebruik in een ontwikkelaarsportaal. Als overheid hebben we [apis.developer.overheid.nl](https://apis.developer.overheid.nl/) als collectieve API catalogus en ontwikkelaarsportaal. #### Ontwikkelaar onboarding @@ -296,7 +297,7 @@ In het geval de back-end functionaliteit wordt ingevuld door meerdere back-end s #### Data Transformaties -Dit betreft functionaliteiten rondom het vertalen van API endpoints naar het achterliggende datamodel. Dit kan plaatsvinden in de API Gateway, integratietoepassingen in de back-end of in back-end (micro)services. +Dit betreft functionaliteiten rondom het vertalen van API endpoints naar het achterliggende datamodel. Dit kan plaatsvinden in de API Gateway, integratietoepassingen in de back-end of in back-end (micro)services. Data transformaties worden, wanneer benodigd, bij voorkeur lokaal in back-end (micro)services toegepast. Niet-domein-specifieke transformaties (bijvoorbeeld voor het vertalen tussen interne en externe representaties of het digitaal ondertekenen van berichten) kunnen ook eventueel centraal in de API Gateway plaatsvinden. @@ -379,10 +380,12 @@ In dit hoofdstuk wordt aandacht besteed aan de positionering van API-Management ### Informatie architectuur -Alle overheden hebben een uitdaging op het gebied van data integratie[[1]](#_ftn1). Hoe faciliteer je gegevensuitwisseling tussen bronnen en afnemers op een efficiënte en beheersbare manier die voldoet aan de eisen van wet- en regelgeving? +Alle overheden hebben een uitdaging op het gebied van data integratie *. Hoe faciliteer je gegevensuitwisseling tussen bronnen en afnemers op een efficiënte en beheersbare manier die voldoet aan de eisen van wet- en regelgeving? Een overheidsinstantie geeft hier het beste invulling aan door organisatiebreed een zogenaamde 'integratielaag' binnen de infrastructuur te positioneren. Dit kan je beschouwen als de gereedschapskist waarbinnen verschillende tools beschikbaar zijn voor data-integratie. Gezien de wereldwijde ontwikkelingen in het gebruik van API's, kan API-Management tooling hierbinnen niet ontbreken. Het is voor overheden essentiële functionaliteit om in lijn met de NORA te kunnen opereren (of specifieker in lijn met Common Ground). +> \* Verder aangeduid als 'integratie', van ook bijvoorbeeld informatie. + #### Referentiecomponenten API-Management tooling omvat de referentiecomponenten API-Gateway, API-Manager en een API-Portaal. Hieronder is beknopt beschreven wat overheidsorganisaties hieronder kunnen verstaan: @@ -391,7 +394,7 @@ API-Management tooling omvat de referentiecomponenten API-Gateway, API-Manager e Een API-Gateway wordt ingezet als poort tot het achterliggende datalandschap. -In cloud-native implementaties zie je steeds vaker een meer gedistribueerd model met behulp van micro gateways (als ingang voor iedere Cloud-omgeving) in plaats van een corporate API-Gateway die alles regelt, eventueel in combinatie met een service mesh[[2]](#_ftn2). Een hybride opstelling is ook mogelijk. +In cloud-native implementaties zie je steeds vaker een meer gedistribueerd model met behulp van micro gateways (als ingang voor iedere Cloud-omgeving) in plaats van een corporate API-Gateway die alles regelt, eventueel in combinatie met een service mesh \**. Een hybride opstelling is ook mogelijk. - API-Manager: zorgt voor de configuratie van de gateway en het beheer van de API's, op basis van patronen en zogenaamde policies. @@ -399,18 +402,20 @@ In cloud-native implementaties zie je steeds vaker een meer gedistribueerd model *Note*: Landelijke ontwikkelingen op dit vlak i.r.t. developer.overheid.nl kunnen er voor zorgen dat deze functionaliteit op termijn centraal landelijk beschikbaar is. +> \** [Service mesh - Wikipedia](https://en.wikipedia.org/wiki/Service_mesh) + In het API-Capability model zijn de functionaliteiten in detail beschreven. [API-Capability model](#api-capability-model) -![](https://github.com/Geonovum/KP-APIs/raw/master/media/API-Management.jpg) +![Functionaliteit binnen API-Management](https://github.com/Geonovum/KP-APIs/raw/master/media/API-Management.jpg) -Figuur 5: Functionaliteit binnen API-Management +> Figuur 6: Functionaliteit binnen API-Management #### Rol van de servicebus -Binnen de integratielaag opereert veelal ook een organisatiebrede servicebus, vaak is er veel energie gestoken in het faciliteren van gegevensstromen via de servicebus (met name op basis van StUF[[3]](#_ftn3)). De API-Management tooling komt naast de servicebus te staan en kan zo aanvullende functionaliteit bieden binnen de integratielaag. Het is voor overheden geen doel om bestaande verbindingen via de servicebus te elimineren of de servicebus uit te faseren. +Binnen de integratielaag opereert veelal ook een organisatiebrede servicebus, vaak is er veel energie gestoken in het faciliteren van gegevensstromen via de servicebus (met name op basis van StUF \***. De API-Management tooling komt naast de servicebus te staan en kan zo aanvullende functionaliteit bieden binnen de integratielaag. Het is voor overheden geen doel om bestaande verbindingen via de servicebus te elimineren of de servicebus uit te faseren. -Wel lijkt gezien de wereldwijde ontwikkelingen de aandacht van integratievraagstukken te gaan verschuiven van de inzet van een organisatiebrede servicebus naar een landschap waarin lightweight API-Management tooling een belangrijke rol speelt. Nieuwe verbindingen (met name voor het ophalen van data) zullen vaker gelegd gaan worden via enkel een API Gateway en de inzet van de servicebus wordt teruggedrongen. Enkel op het gebied waar de huidige servicebus specifieke toegevoegde waarde levert, wordt deze voor overheden nog ingezet voor nieuwe verbindingen (eventueel in combinatie met een API Gateway). Dit zal naar verwachting voor overheden de meest voor de hand liggende oplossing zijn, gezien het huidige applicatielandschap. +Wel lijkt gezien de wereldwijde ontwikkelingen de aandacht van integratievraagstukken te gaan verschuiven van de inzet van een organisatiebrede servicebus naar een landschap waarin lightweight API-Management tooling een belangrijke rol speelt. Nieuwe verbindingen (met name voor het ophalen van data) zullen vaker gelegd gaan worden via enkel een API Gateway en de inzet van de servicebus wordt teruggedrongen. Enkel op het gebied waar de huidige servicebus specifieke toegevoegde waarde levert, wordt deze voor overheden nog ingezet voor nieuwe verbindingen (eventueel in combinatie met een API Gateway). Dit zal naar verwachting voor overheden de meest voor de hand liggende oplossing zijn, gezien het huidige applicatielandschap. Toegevoegde waarde servicebus i.r.t. API-Gateway: @@ -419,16 +424,7 @@ Toegevoegde waarde servicebus i.r.t. API-Gateway: - Orkestratie/logica - Gegevensautorisatie op doelbinding (bij gemeentelijke servicebussen vaak geïntegreerd) - -* * * * * - -[[1]](#_ftnref1) Verder aangeduid als 'integratie', van ook bijvoorbeeld informatie. - -[[2]](#_ftnref2) [Service mesh - Wikipedia](https://en.wikipedia.org/wiki/Service_mesh) - -[[3]](#_ftnref3) Zie [StUF Berichtenstandaard - GEMMA Online](https://www.gemmaonline.nl/index.php/StUF_Berichtenstandaard) - -* * * * * +> \*** Zie [StUF Berichtenstandaard - GEMMA Online](https://www.gemmaonline.nl/index.php/StUF_Berichtenstandaard) ## Informatiemodel & API @@ -452,7 +448,7 @@ Een informatiemodel beschrijft een werkelijkheid. We onderscheiden vier niveaus De volgende begrippen worden gehanteerd in dit hoofdstuk: -- *Informatiemodel* : Niveau 3 - Logisch gegevensmodel / datamodel +- *Informatiemodel* : Niveau 3 - Logisch gegevensmodel / datamodel - *Resource model* : Niveau 4 - Fysiek / technisch datamodel (directe datamodel van een API) - *Applicatie data model* : Niveau 4 - Fysiek / technisch datamodel (datamodel van een achterliggend systeem) @@ -462,9 +458,9 @@ Via een API ontsluit een applicatie data en functionaliteit. Hierbij helpt het o Het Resource Model is als het ware een logische view op het achterliggende Data Model. -![alt text](https://github.com/Geonovum/KP-APIs/raw/master/overleggen/Werkgroep%20API%20architectuur/uitwerkingen/media/API-Informatiemodel.png) +![Resource Model](https://github.com/Geonovum/KP-APIs/raw/master/overleggen/Werkgroep%20API%20architectuur/uitwerkingen/media/API-Informatiemodel.png) -Figuur 6: Resource Model +> Figuur 7: Resource Model Wanneer het Resource Model 1 op 1 gelijk is aan het achterliggende Data Model is de vertaling/mapping eenvoudig en kan dit ook geautomatiseerd worden : het Resource Model en de API kunnen bijvoorbeeld worden gegenereerd vanuit het Applicatie Data Model. @@ -484,18 +480,19 @@ Voor complexe Domeinen of gecombineerde Diensten waarbij meerdere bronnen worden Het Resource Model als logische view op achterliggende datamodellen heeft ook als voordeel dat op de laag van het Resource Model al integratie van data modellen kan plaatsvinden nog voordat de achterliggende modellen zijn aangepast of volledig geïntegreerd. Een (nieuw) geïntegreerd Resource model over meerdere achterliggende datamodellen heen kan zo databronnen integreren en aanbieden. Met behulp van een geïntegreerd resourcemodel op het niveau van API's kan sneller gestandaardiseerd worden en kan men ook sneller innoveren. -![alt text](https://github.com/Geonovum/KP-APIs/raw/master/overleggen/Werkgroep%20API%20architectuur/uitwerkingen/media/API-Infomodel2.png) +![Geïntegreerd Resource Model](https://github.com/Geonovum/KP-APIs/raw/master/overleggen/Werkgroep%20API%20architectuur/uitwerkingen/media/API-Infomodel2.png) -Figuur 7: Geïntegreerd Resource Model +> Figuur 8: Geïntegreerd Resource Model ### Aanbevelingen #### Verbindt het Resource Model met een Informatiemodel Bij het aanbieden van data via een API is het van groot belang om de verbinding met een informatiemodel te hebben en deze verbinding ook te beschrijven en te publiceren bij de API documentatie. -* Dit bevordert begrip bij afnemers, zodat zij de ruwe data goed kunnen interpreteren. -* Dit houdt de API beheersbaar en zorgt dat de API gemakkelijker kan mee-evolueren met het informatielandschap (immers wijzigingen in het informatiemodel kunnen dan gerelateerd worden aan wijzigingen in de API). -* Wanneer een API informatie uit een stelsel van gegevensbronnen ontsluit bevordert dit interoperabiliteit in het stelsel. + +- Dit bevordert begrip bij afnemers, zodat zij de ruwe data goed kunnen interpreteren. +- Dit houdt de API beheersbaar en zorgt dat de API gemakkelijker kan mee-evolueren met het informatielandschap (immers wijzigingen in het informatiemodel kunnen dan gerelateerd worden aan wijzigingen in de API). +- Wanneer een API informatie uit een stelsel van gegevensbronnen ontsluit bevordert dit interoperabiliteit in het stelsel. Het Resource Model van een API is een (of mogelijk meerdere, afhankelijk van uitwisselformaat) Niveau 4 - Fysiek / technisch datamodel(len). Het is namelijk een model van de uitwisseling van gegevens in een concreet uitwisselformaat. Bijvoorbeeld gespecificeerd in een OAS document. [OAS](https://www.openapis.org/). Het is echter belangrijk om de verbinding met een Niveau 3: - Logisch informatie- of gegevensmodel uit te drukken, omdat dit een implementatie-onafhankelijk model is, wat begrip, maar ook interoperabiliteit, bevordert. Het bevordert interoperabiliteit met andere Niveau 3 informatiemodellen in een stelsel, maar biedt ook één overkoepelend informatiemodel wanneer er sprake is van gegevensuitwisseling conform verschillende Niveau 4 informatiemodellen gebaseerd op hetzelfde Niveau 3 informatiemodel. @@ -534,11 +531,11 @@ Onderstaande afbeelding geeft een overzicht van standaard componenten in een API ![API Security Architectuur diagram](https://github.com/Geonovum/KP-APIs/raw/master/overleggen/Werkgroep%20API%20architectuur/uitwerkingen/media/api-security-architecture.png) -Figuur 8: API Security +> Figuur 9: API Security #### Actors en Clients -Onderstaand overzicht beschrijft de actoren en API Clients welke een rol spelen bij API beveiliging uit bovenstaand diagram. +Onderstaand overzicht beschrijft de actoren en API Clients welke een rol spelen bij API beveiliging uit bovenstaand diagram. - **Eindgebruikers:** Eindgebruikers welke door middel van devices en client apps gebruik maken van API's. - **Client ontwikkelaars:** Ontwikkelaars van client API gebruikende client apps voor verschillende devices. @@ -551,13 +548,13 @@ Onderstaand overzicht beschrijft de actoren en API Clients welke een rol spelen Onderstaand overzicht beschrijft de componenten welke een rol spelen bij API beveiliging uit bovenstaand diagram. -- **Identity Provider:** Biedt de mogelijkheid aan eindgebruikers en Client applicaties om zichzelf te identificeren en Authentiseert deze. Geeft een authenticatie token af aan de Client applicatie waarmee deze API endpoints kan benaderen. +- **Identity Provider:** Biedt de mogelijkheid aan eindgebruikers en Client applicaties om zichzelf te identificeren en Authentiseert deze. Geeft een authenticatie token af aan de Client applicatie waarmee deze API endpoints kan benaderen. In de context van OAuth wordt het component wat tokens uitgeeft vaak aangeduid als de **Authorization Server (AS)**. - **API Gateway:** De toegangspoort tot het achterliggende applicatie landschap. Alle API interactie verloopt via de API Gateway, waardoor de API Gateway een centrale rol heeft in de API beveiliging. Over het algemeen bevat de API Gateway een aantal traffic policies (zie volgend punt) welke bij elk API verzoek worden gevalideerd en voert de API Gateway initiële autorisatie van API verzoeken uit. Deze autorisatie omvat minimaal een controle of de ontvangen verzoeken van correcte Access Tokens zijn voorzien en kan eventueel role-based autorisaties toepassen. De API Gateway kan een verbinding met de Identity Provider hebben voor het geval door de Identity Provider afgegeven tokens onvoldoende informatie bevatten om autorisaties toe te passen. - **Traffic Policies:** Een verzameling policies welke worden toegepast op al het API verkeer, of een specifiek deel daarvan. Voorbeelden zijn *Rate Limiting / Throttling*, *SLA Management* en *Input validatie*. Over het algemeen bieden API Gateways de mogelijkheden om traffic policies direct in te bouwen. - **Gebruiker / client / rol beheer:** Het beheren van gebruikers van de API tooling, zoals beheerders, API developers en client developers, geregistreerde Client applicaties en een mapping van eindgebruikers identiteiten en rollen naar specifieke autorisaties. Dit is *niet* de identity store welke credentials van eindgebruikers bevat; dat gedeelte is de verantwoordelijkheid van de Identity Provider. - **Sleutel beheer:** Beheert het sleutelmateriaal dat wordt gebruikt voor versleuteling en ondertekening van berichten welke worden uitgewisseld tussen API Gateway, Identity Provider en Client applicaties. - **Logging, Monitoring, Analytics, Caching:** Cross-cutting functionaliteiten welke op verschillende en/of meerdere plekken in het landschap geïmplementeerd kunnen worden. Voor al deze functionaliteiten is het van belang dat deze in lijn met AVG richtlijnen worden opgezet. Bij caching is het daarnaast belangrijk cache invalidaties te implementeren om te voorkomen dat verouderde cache data kan worden teruggehaald, zeker als daar privacy gevoelige informatie in kan staan. -- **Back-end Services:** Applicaties die de daadwerkelijke resources implementeren. +- **Back-end Services:** Applicaties die de daadwerkelijke resources implementeren. ### Principes @@ -579,7 +576,7 @@ Verder moeten de aanbevelingen in de volgende externe documenten worden overwoge #### Gedelegeerde Identificatie en Authenticatie -Authenticatie beschrijft het met een bepaalde zekerheid vaststellen of een persoon of systeem echt degene is die deze zegt te zijn. +Authenticatie beschrijft het met een bepaalde zekerheid vaststellen of een persoon of systeem echt degene is die deze zegt te zijn. In de context van API's is authenticatie van toepassing op de API Client, oftewel de applicatie die de API resources benadert, en de eindgebruiker, oftewel de persoon namens wie de API Client de API resources benadert. @@ -599,10 +596,13 @@ Een belangrijk component bij autorisaties in de context van API's is de API Gate Voor de implementatie van *domein-specifieke autorisaties* in de back-ends kunnen tevens microgateways of een service mesh oplossing worden gekozen. Bijkomend voordeel van het gebruik van een service mesh is dat deze standaard werken op basis van zero-trust networking. - +Bovenstaand figuur beschrijft de basis van de API Security architectuur. Binnen de Nederlandse overheid zijn meerdere niveau's van beveiliging (zie ook de BIO 2.0) en authenticatie dan in reguliere commerciële situaties. Denk hierbij bijvoorbeeld aan het redundant aanbieden van API toegang vis een besloten netwerk als Diginetwerk of het afdwingen van mTLS en authenticatie met een PKIO certificaat om er zo zeker van te zijn dat de client ook echt van een identificeerbare en erkende organisatie is. + +Daarnaast zijn er ook nog flows om tokens uit te geven aan gebruikers op basis van OAuth / OIDC en diepgaandere technieken zoals Externalized Authorization Management (EAM) om centraal beheerde policies met toegangsregels af te dwingen met PBAC op basis van AuthZen. Tot slot is het voor uitwisseling van gegevens tussen overheidsorganisaties ook nog aan te bevelen de FSC standaarden toe te passen voor G2G verkeer. + +Het spreekt voor zich dat niet al deze security aspecten gestapeld moeten worden toegepast op een API en dat er per situatie en doelgroep een risico analyse en bijbehorende maatregelen moeten worden toegepast. De module Access Control geeft hierin meer context en richting. ### Referenties @@ -612,3 +612,79 @@ TBD: input van Eelco. --> - [NORA - Beschikbaarheid principe](https://www.noraonline.nl/wiki/Beschikbaarheid) - [NORA - Integriteit principe](https://www.noraonline.nl/wiki/Integriteit) - [NORA - Vertrouwelijkheid principe](https://www.noraonline.nl/wiki/Vertrouwelijkheid_%28principe%29) +- [Federatieve Toegangsverlening (FTV)](https://vng-realisatie.github.io/ftv/) +- [Federatieve Service Connectiviteit (FSC)](https://fsc-standaard.nl/) +- [Open Authenticatie (OAUTH)](https://gitdocumentatie.logius.nl/publicatie/api/oauth/) +- [OpenID Connect (OIDC)](https://gitdocumentatie.logius.nl/publicatie/api/oidc/) +- [Module Access control](https://docs.geostandaarden.nl/api/API-Strategie-mod-access-control/) + +## Verdieping Orkestratie + +API orkestratie is een cruciaal concept binnen de moderne ICT-architectuur, vooral in de context van het integreren van verschillende applicaties en services. Het stelt organisaties in staat om complexe workflows te beheren door verschillende API's te coördineren en hun interacties te stroomlijnen. Dit biedt voordelen zoals verhoogde efficiëntie, verbeterde dataconsistentie en een betere gebruikerservaring. + +### Wat is API Orkestratie? + +API orkestratie verwijst naar het proces waarbij meerdere API-aanroepen worden gecoördineerd om een specifieke taak of workflow uit te voeren. Dit kan bijvoorbeeld inhouden dat gegevens van verschillende bronnen worden samengevoegd of dat meerdere services in een bepaalde volgorde worden aangeroepen om een einddoel te bereiken. + +### Uitgangspunten + +Uitgangspunt is de bestaande registraties met de bestaande registratie-processen. + +Met betrekking tot security zijn er diverse aandachtspunten: + +- Data integriteit. Dmv signing zou van individuele gegevens kunnen worden aangetoond wat de authentieke bron is en of dat deze identiek zijn aan de authentieke gegevens. Interessant vraagstuk is wat dit betekent als gegevens tijdens het orkestreren worden getransformeerd. Mogelijk raakvlakken met de [RDF Dataset Canonicalization](https://www.w3.org/TR/rdf-canon/) standaard. +- Authenticatie/autorisatie. Bij orkestratie worden verschillende requests uitgevoerd vanuit mogelijk verschillende identiteiten, verschillende identity stores en verschillende scopes/audiences. Hierbij kan zowel een transparant als niet-transparant model worden toegepast. Deze willen we beiden beschrijven. Relevante standaarden zijn [FSC](https://commonground.gitlab.io/standards/fsc/) en [OAuth Token Exchange](https://datatracker.ietf.org/doc/html/rfc8693). + +### Use cases + +Er zijn reeds enkele voorbeelden van use cases waarbij orkestratie een belangrijke rol speelt: + +- [IMX-Geo](https://www.geonovum.nl/geo-standaarden/imx-geo-semantisch-model-basis-en-kernregistraties) (Geonovum), Bestuurlijke Gebieden (BZK), Gebouwdossier (Kadaster) +- [Diverse Digital Twin use cases](https://www.geonovum.nl/themas/digital-twins) +- [Digilab](https://digilab.overheid.nl/) use cases: opkopersbescherming (RVIG/VNG), maximale huurverhoging (Belastingdienst) + +### Aandachtsgebieden van Orkestratie + +Interessante onderwerpen die sterk gerelateerd zijn aan orkestratie zij: + +- Fouttolerantie (graceful degradation, resiliency, retry policies, automatisch terugmelden). +- Doodlopende links (afwijkingen van informatiemodel, actualiteits-issues, etc.) +- Mapping en herleidbaarheid (zie IMX) +- Historie en tijdreizen (separate module in concept) +- Batching (separate module in concept) + +- Orkestratie in OAuth (o.a. Token Exchange, eHerkenning, FSC, etc.) + +### IMX + +Kadaster heeft in samenwerking met Geonovum het IMX initiatief gestart. Dit initiatief heeft als ambitie om basisregistraties (en andere bronnen) in samenhang te kunnen bevragen door middel van API orkestratie. Om op een efficiënte manier te kunnen orkestreren moeten bron API’s voldoen aan diverse randvoorwaarden. De uitdaging is om te onderzoeken welke randvoorwaarden dit zijn en op welke manier deze gestandaardiseerd zouden kunnen worden als design rules. + +### Arazzo + +De [Arazzo-specificatie](https://www.openapis.org/arazzo) is een nieuwe, door de gemeenschap gedreven standaard die is ontwikkeld onder het OpenAPI-initiatief, met als doel de documentatie en interactie van API's te verbeteren. Het biedt een **programmeertaal-onafhankelijk** kader om reeksen API-aanroepen en hun afhankelijkheden te definiëren, waardoor de communicatie van workflows duidelijker wordt. + +Dit project bevindt zich echter nog in een vroeg stadium. Ook is het maar de vraag in hoeverre (commerciële) software vendors erbij gebaat zouden zijn een dergelijke standaard te implenteren. Verder wordt de kanttekening geplaatst dat benodigde stappen bij orkestratie ook dynamisch kunnen worden berekend, zoals bij IMX wordt gedaan. In dat geval is het specificeren van een workflow niet relevant. + +#### Belangrijkste Kenmerken + +- **Deterministische Workflows**: Arazzo maakt zowel menselijke leesbare als machine-leesbare documentatie mogelijk, wat de ervaring voor API-aanbieders en -gebruikers verbetert. +- **Toepassingen**: Interactieve workflowdocumentatie Automatische documentgeneratie Code- en SDK-generatie op basis van functionele gebruiksgevallen Automatisering van testgevallen en nalevingscontroles AI-gestuurde deterministische API-aanroep + +#### Relatie met OpenAPI + +Arazzo aanvult de bestaande OpenAPI-specificatie door beschrijvingen van **groepen API's** en hun interacties mogelijk te maken, in plaats van alleen individuele API's. Deze bredere scope ondersteunt automatisering en codegeneratie, met als uiteindelijke doel de waarde die uit API's wordt gehaald te maximaliseren.Het project staat open voor deelname van de gemeenschap, met middelen beschikbaar op GitHub voor degenen die geïnteresseerd zijn in bijdragen of meer willen leren over de specificatie. + +### Federatieve Toegangsverlening in combinatie met Orkestratie + +Voor een succesvolle orkestratie is het van belang dat alle gateway's, die de api's beschermen die in de orkestratie worden aangeroepen, op een eenduidige en voorspelbare manier de policies afdwingen. Bij het opzetten van een Orkestratie is het dan ook niet alleen van belang om aandacht te geven aan Data integriteit en Authenticatie/autorisatie maar indien er op de API's ook Policy Based Access Control (PBAC) of Externalized Authorization Management (EAM) wordt toegepast moeten deze aspecten als aandachtspunt worden meegenomen. + +Overweeg bij het aanbieden van een proces api als interface voor een orkestratie dat het belangrijk is dat alle policies van de system api's optellen en deze policies ook afgedwongen moeten worden in de proces api. + +Het Federatief Datastelsel (FDS) heeft hiervoor verschillende faciliterende stelselfuncties benoemd. + +- Poortwachter, +- Marktmeester, +- Helpdesk, +- Expertisecentrum. + +Kijk voor een overzicht van alle Stelselfuncties van het Federatief Datastelsel op de [Stelselfuncties pagina.](https://federatief.datastelsel.nl/kennisbank/stelselfuncties/) From b32baca68934d59b20805c4511d112ed7b6d214c Mon Sep 17 00:00:00 2001 From: Martin van der Plas Date: Thu, 25 Sep 2025 18:04:58 +0200 Subject: [PATCH 2/3] Update config.js --- API-strategie-algemeen/Architectuur/config.js | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/API-strategie-algemeen/Architectuur/config.js b/API-strategie-algemeen/Architectuur/config.js index cb2c53bb..825ad527 100644 --- a/API-strategie-algemeen/Architectuur/config.js +++ b/API-strategie-algemeen/Architectuur/config.js @@ -13,7 +13,7 @@ //-- . . . . . : 20220412 - EJR - Vastgestelde versie van 09-03-2022 gemaakt //-- . . . . . : 20220909 - MvdP - Concept versie opzet voor Modulaire opbouw //-- . . . . . : 20220909 - Ft - Versie ter vaststelling voor Modulaire opbouw -//-- +//-- . . . . . : 20250925 - MvdP - Orkestratie en Security bijgewerkt //------------------------------------------------------------------------------------- //-- Postprocessors ------------------------------------------------------------------- @@ -42,11 +42,11 @@ function custGHPG(respecConfig) var respecConfig = { - specStatus: "GN-DEF", + specStatus: "GN-VV", specType: "HR", pubDomain: "api", - //publishDate: "2023-01-13", - previousPublishDate: "2023-12-21", + publishDate: "2025-09-25", + previousPublishDate: "2024-03-12", previousMaturity: "GN-DEF", edDraftURI: "https://geonovum.github.io/KP-APIs/API-strategie-algemeen/Architectuur/", editors: From 4259d3db63063dd0bc4f07a711ba31ca46063c4d Mon Sep 17 00:00:00 2001 From: Joost Farla Date: Wed, 15 Oct 2025 16:04:18 +0200 Subject: [PATCH 3/3] Fix links + markup --- .../Architectuur/architectuur.md | 97 +++++++++---------- 1 file changed, 48 insertions(+), 49 deletions(-) diff --git a/API-strategie-algemeen/Architectuur/architectuur.md b/API-strategie-algemeen/Architectuur/architectuur.md index 20a08764..85ca9698 100644 --- a/API-strategie-algemeen/Architectuur/architectuur.md +++ b/API-strategie-algemeen/Architectuur/architectuur.md @@ -1,10 +1,9 @@ - # Architectuur -> *Dit hoofdstuk gaat in op de vraag: Hoe kan je je applicatie landschap -> inrichten zodat je APIs kan aanbieden. Welke componenten zijn hiervoor -> nodig. Hoe ga je om met opschalen, beschikbaarheid. Wat zijn afwegingen om -> beveiliging al dan niet toe te passen.* +Dit hoofdstuk gaat in op de vraag: Hoe kan je je applicatie landschap +inrichten zodat je APIs kan aanbieden? Welke componenten zijn hiervoor +nodig? Hoe ga je om met opschalen, beschikbaarheid? Wat zijn afwegingen om +beveiliging al dan niet toe te passen? ## Inleiding @@ -28,6 +27,7 @@ Overheidsorganisaties bieden diensten aan Burgers, Bedrijven en andere Overheids Onderstaande figuur geeft de dienstverlening middels API's aan de verschillende partijen grafisch weer. ![API Diensten voor Burgers, Bedrijven en Overheden](https://github.com/Geonovum/KP-APIs/raw/master/overleggen/Werkgroep%20API%20architectuur/uitwerkingen/media/API-arch-v22.png) + > Figuur 2: API Diensten voor Burgers, Bedrijven en Overheden Toelichting API koppelvlakken: @@ -45,7 +45,7 @@ Toelichting API doelgroepen: In de bovenstaande figuur wordt ook het belang van standaardisatie van API's zichtbaar: -Burgers, Bedrijven (en ook Overheidsorganisaties zelf) gebruiken (doorgaans) de API's van meerdere Overheidsorganisaties. Wanneer de verschillende 'API contactoppervlakken' uniform zijn (ook over organisaties heen) kunnen dienstafnemers gemakkelijker (en dus sneller en met minder kosten) gebruik maken van 'Overheids API's' +Burgers, Bedrijven (en ook Overheidsorganisaties zelf) gebruiken (doorgaans) de API's van meerdere Overheidsorganisaties. Wanneer de verschillende 'API contactoppervlakken' uniform zijn (ook over organisaties heen) kunnen dienstafnemers gemakkelijker (en dus sneller en met minder kosten) gebruik maken van 'Overheids API's' ## Typologie van API's @@ -68,6 +68,7 @@ Een overheidsorganisatie ontsluit zijn diensten naar andere overheidsorganisatie In onderstaande figuur wordt dit visueel weergegeven. ![Soorten API's](https://github.com/Geonovum/KP-APIs/raw/master/overleggen/Werkgroep%20API%20architectuur/uitwerkingen/media/govapi.png) + > Figuur 3 : Soorten API's **Afkortingen**: @@ -81,7 +82,7 @@ In onderstaande figuur wordt dit visueel weergegeven. Deze indeling maakt onderscheid in Systeem, Proces, Convenience API's: - System API (werkt op het niveau van de databron); -- Process API (doet aan orkestratie door één of meerdere System API's aan te roepen); +- Process API (doet aan orkestratie door één of meerdere System API's aan te roepen); - Convenience of Experience API (beantwoord één specifieke gebruikersvraag); ### Business / Exposure @@ -118,6 +119,7 @@ In onderstaand voorbeeld is dit: - Met doelbinding ![Virtuele varianten van een API](https://github.com/Geonovum/KP-APIs/raw/master/overleggen/Werkgroep%20API%20architectuur/uitwerkingen/media/api-virt.png) + > Figuur 4 : Virtuele varianten van een API ### API Language styles @@ -134,17 +136,18 @@ Onderstaande indeling gaat uit van de bij de API toegepaste 'language' style. Om als organisatie API's aan te bieden aan andere partijen op een gecontroleerde en beheersbare manier moet je bepaalde functionaliteit bieden, processen inregelen en ondersteuning aanbieden. -Het onderstaande API Capability model geeft weer aan welke onderwerpen men aandacht moet schenken bij het inrichten van API gedreven dienstverlening. De onderwerpen zijn gegroepeerd in de categorieën *Registratie & gebruik*, *Realisatie & beheer* en *Verkeersstroom beheer*. +Het onderstaande API Capability model geeft weer aan welke onderwerpen men aandacht moet schenken bij het inrichten van API gedreven dienstverlening. De onderwerpen zijn gegroepeerd in de categorieën _Registratie & gebruik_, _Realisatie & beheer_ en _Verkeersstroom beheer_. ![API Capability Model](https://github.com/Geonovum/KP-APIs/raw/master/media/API-Capability.png) + > Figuur 5 : API Capability Model ### Registratie & Gebruik Deze categorie bevat capabilities voor het ondersteunen van ontwikkelaars die gebruik willen maken van de aangeboden API's. De capabilities binnen deze categorie zijn onderverdeeld in de volgende sub-categorieën: -- *Aanmelden & Registratie*: functionaliteiten waarmee nieuwe gebruikers zichzelf en hun applicaties kunnen registreren om gebruik te maken van aangeboden API's; -- *Ontdekken*: functionaliteiten waarmee gebruikers kennis over aangeboden API's op kunnen doen en delen. +- _Aanmelden & Registratie_: functionaliteiten waarmee nieuwe gebruikers zichzelf en hun applicaties kunnen registreren om gebruik te maken van aangeboden API's; +- _Ontdekken_: functionaliteiten waarmee gebruikers kennis over aangeboden API's op kunnen doen en delen. Over het algemeen biedt een API leverancier capabilities ten behoeve van API gebruik in een ontwikkelaarsportaal. Als overheid hebben we [apis.developer.overheid.nl](https://apis.developer.overheid.nl/) als collectieve API catalogus en ontwikkelaarsportaal. @@ -196,10 +199,10 @@ Naast het kunnen inzien van documentatie en het gebruik maken van sandbox API's, Realisatie & Beheer gaat over het (door)ontwikkelen van API's, het beheren van de API lifecycle van ideatie tot uitfasering en het beheren van het API ecosysteem. De capabilities binnen deze categorie zijn onderverdeeld in de volgende sub-categorieën: -- *Realisatie*: capabilities met betrekking tot het aanbieden van nieuwe API endpoints en de doorontwikkeling van bestaande; -- *API Governance*: standaarden, afspraken en richtlijnen rondom het aanbieden van API's en de processen om hieraan te voldoen; -- *API Lifecycle beheer*: capabilities met betrekking tot de sturing op een uniform API portfolio en lifecycle management van de API's; -- *Platform beheer*: functionaliteiten met betrekking tot het kunnen beheren van het platform of ecosysteem waarin de API's opereren. +- _Realisatie_: capabilities met betrekking tot het aanbieden van nieuwe API endpoints en de doorontwikkeling van bestaande; +- _API Governance_: standaarden, afspraken en richtlijnen rondom het aanbieden van API's en de processen om hieraan te voldoen; +- _API Lifecycle beheer_: capabilities met betrekking tot de sturing op een uniform API portfolio en lifecycle management van de API's; +- _Platform beheer_: functionaliteiten met betrekking tot het kunnen beheren van het platform of ecosysteem waarin de API's opereren. #### Ontwerp @@ -221,7 +224,7 @@ Wanneer bij het API Ontwerp gebruik gemaakt wordt van de OAS standaard, bieden z #### Test -Dit betreft het testen van API endpoints tegen de specificatie. Waar mogelijk gebeurt dit geautomatiseerd. Op het gebied van *syntactische* tests biedt veel test tooling ondersteuning voor het importeren van Open API Specificaties; voor het uitvoeren van *semantische* tests is het vaak noodzakelijk dat testdata wordt geprepareerd en use cases worden uitgewerkt in test cases. +Dit betreft het testen van API endpoints tegen de specificatie. Waar mogelijk gebeurt dit geautomatiseerd. Op het gebied van _syntactische_ tests biedt veel test tooling ondersteuning voor het importeren van Open API Specificaties; voor het uitvoeren van _semantische_ tests is het vaak noodzakelijk dat testdata wordt geprepareerd en use cases worden uitgewerkt in test cases. #### Policy Definitie @@ -282,10 +285,10 @@ Verkeersstroom beheer gaat over de functionaliteiten die te maken hebben met ver De capabilities binnen deze categorie zijn onderverdeeld in de volgende sub-categorieën: -- *Mediatie & Orkestratie*: het verwerken, valideren, routeren en bewerken van API verzoeken en antwoorden om een gebruiksvriendelijke en uniforme beleving aan API clients te kunnen bieden; -- *Telemetrie & Inzicht*: het meten en inzichtelijk maken van API verzoeken en antwoorden om inzicht te krijgen in het gebruik van API's en de gezondheid van het platform; -- *Servicelevel Beheer*: het definieren en afdwingen van afspraken rondom beschikbaarheid en de toegestane hoeveelheid API verzoeken dat een API client mag doen, eventueel gebaseerd op staffels voor doorbelasting; -- *Beveiliging*: functionaliteiten rondom de beveiliging van API endpoints en de data en processen die hiermee ontsloten worden. +- _Mediatie & Orkestratie_: het verwerken, valideren, routeren en bewerken van API verzoeken en antwoorden om een gebruiksvriendelijke en uniforme beleving aan API clients te kunnen bieden; +- _Telemetrie & Inzicht_: het meten en inzichtelijk maken van API verzoeken en antwoorden om inzicht te krijgen in het gebruik van API's en de gezondheid van het platform; +- _Servicelevel Beheer_: het definieren en afdwingen van afspraken rondom beschikbaarheid en de toegestane hoeveelheid API verzoeken dat een API client mag doen, eventueel gebaseerd op staffels voor doorbelasting; +- _Beveiliging_: functionaliteiten rondom de beveiliging van API endpoints en de data en processen die hiermee ontsloten worden. #### Mediatie & Orkestratie @@ -317,7 +320,7 @@ Ook kan protocol conversie nodig zijn om back-end systemen die gebruik maken van #### Logging & Audit trail -Geeft inzicht in de verkeersstromen tussen API Clients, API Gateway en het achterliggende applicatie landschap en zorgt ervoor dat alle handelingen herleidbaar zijn door inzicht te geven in historische verkeersstromen, ten behoeve van audit doeleinden (i.h.k.v. privacy, beveiliging en transparantie). +Geeft inzicht in de verkeersstromen tussen API Clients, API Gateway en het achterliggende applicatie landschap en zorgt ervoor dat alle handelingen herleidbaar zijn door inzicht te geven in historische verkeersstromen, ten behoeve van audit doeleinden (i.h.k.v. privacy, beveiliging en transparantie). Onder andere de volgende informatie kan inzichtelijk worden gemaakt: @@ -347,10 +350,10 @@ In sommige gevallen kan er voor gekozen worden om API gebruik door te belasten. Er bestaan verschillende doorbelastingsmodellen, welke vallen onder de volgende hoofdcategorieën: -- *Vrij:* de API is vrij te gebruiken zonder kosten. -- *Betaald:* gebruikers van de API moeten betalen voor het gebruik ervan. Onder deze categorie vallen verschillende subcategorieën, zoals Freemium, Tiered, Pay-as-you-go en doorbelasting op basis van een vaste prijs per tijdseenheid. -- *Indirect:* gebruikers van de API betalen niet direct voor het gebruik ervan, maar dragen indirect bij aan het business model van de API aanbieder, waardoor API gebruik geld oplevert voor de API aanbieder. -- *Affiliate:* vergelijkbaar met indirect, behalve dat de API aanbieder gebruikers van API's betaalt om het gebruik van de API's zoveel mogelijk te stimuleren. +- _Vrij:_ de API is vrij te gebruiken zonder kosten. +- _Betaald:_ gebruikers van de API moeten betalen voor het gebruik ervan. Onder deze categorie vallen verschillende subcategorieën, zoals Freemium, Tiered, Pay-as-you-go en doorbelasting op basis van een vaste prijs per tijdseenheid. +- _Indirect:_ gebruikers van de API betalen niet direct voor het gebruik ervan, maar dragen indirect bij aan het business model van de API aanbieder, waardoor API gebruik geld oplevert voor de API aanbieder. +- _Affiliate:_ vergelijkbaar met indirect, behalve dat de API aanbieder gebruikers van API's betaalt om het gebruik van de API's zoveel mogelijk te stimuleren. #### Identificatie & Authenticatie @@ -380,7 +383,7 @@ In dit hoofdstuk wordt aandacht besteed aan de positionering van API-Management ### Informatie architectuur -Alle overheden hebben een uitdaging op het gebied van data integratie *. Hoe faciliteer je gegevensuitwisseling tussen bronnen en afnemers op een efficiënte en beheersbare manier die voldoet aan de eisen van wet- en regelgeving? +Alle overheden hebben een uitdaging op het gebied van data integratie \*. Hoe faciliteer je gegevensuitwisseling tussen bronnen en afnemers op een efficiënte en beheersbare manier die voldoet aan de eisen van wet- en regelgeving? Een overheidsinstantie geeft hier het beste invulling aan door organisatiebreed een zogenaamde 'integratielaag' binnen de infrastructuur te positioneren. Dit kan je beschouwen als de gereedschapskist waarbinnen verschillende tools beschikbaar zijn voor data-integratie. Gezien de wereldwijde ontwikkelingen in het gebruik van API's, kan API-Management tooling hierbinnen niet ontbreken. Het is voor overheden essentiële functionaliteit om in lijn met de NORA te kunnen opereren (of specifieker in lijn met Common Ground). @@ -394,15 +397,13 @@ API-Management tooling omvat de referentiecomponenten API-Gateway, API-Manager e Een API-Gateway wordt ingezet als poort tot het achterliggende datalandschap. -In cloud-native implementaties zie je steeds vaker een meer gedistribueerd model met behulp van micro gateways (als ingang voor iedere Cloud-omgeving) in plaats van een corporate API-Gateway die alles regelt, eventueel in combinatie met een service mesh \**. Een hybride opstelling is ook mogelijk. +In cloud-native implementaties zie je steeds vaker een meer gedistribueerd model met behulp van micro gateways (als ingang voor iedere Cloud-omgeving) in plaats van een corporate API-Gateway die alles regelt, eventueel in combinatie met een [service mesh](https://en.wikipedia.org/wiki/Service_mesh). Een hybride opstelling is ook mogelijk. - API-Manager: zorgt voor de configuratie van de gateway en het beheer van de API's, op basis van patronen en zogenaamde policies. - API-Portaal: een portaal waarin de aangeboden API's aan het brede publiek worden gepresenteerd. Via de specificaties kunnen ze een proeftuin creëren. Gebruikers zijn medewerkers geïnteresseerd in de ontwikkeling en het gebruik van API's. Dit kunnen zowel medewerkers van de overheid zijn, als ook externen (bijvoorbeeld van software leveranciers of ketenpartners). -*Note*: Landelijke ontwikkelingen op dit vlak i.r.t. developer.overheid.nl kunnen er voor zorgen dat deze functionaliteit op termijn centraal landelijk beschikbaar is. - -> \** [Service mesh - Wikipedia](https://en.wikipedia.org/wiki/Service_mesh) +_Note_: Landelijke ontwikkelingen op dit vlak i.r.t. developer.overheid.nl kunnen er voor zorgen dat deze functionaliteit op termijn centraal landelijk beschikbaar is. In het API-Capability model zijn de functionaliteiten in detail beschreven. [API-Capability model](#api-capability-model) @@ -413,7 +414,7 @@ In het API-Capability model zijn de functionaliteiten in detail beschreven. #### Rol van de servicebus -Binnen de integratielaag opereert veelal ook een organisatiebrede servicebus, vaak is er veel energie gestoken in het faciliteren van gegevensstromen via de servicebus (met name op basis van StUF \***. De API-Management tooling komt naast de servicebus te staan en kan zo aanvullende functionaliteit bieden binnen de integratielaag. Het is voor overheden geen doel om bestaande verbindingen via de servicebus te elimineren of de servicebus uit te faseren. +Binnen de integratielaag opereert veelal ook een organisatiebrede servicebus, vaak is er veel energie gestoken in het faciliteren van gegevensstromen via de servicebus (met name op basis van de [StUF Berichtenstandaard](https://www.gemmaonline.nl/wiki/StUF-standaarden). De API-Management tooling komt naast de servicebus te staan en kan zo aanvullende functionaliteit bieden binnen de integratielaag. Het is voor overheden geen doel om bestaande verbindingen via de servicebus te elimineren of de servicebus uit te faseren. Wel lijkt gezien de wereldwijde ontwikkelingen de aandacht van integratievraagstukken te gaan verschuiven van de inzet van een organisatiebrede servicebus naar een landschap waarin lightweight API-Management tooling een belangrijke rol speelt. Nieuwe verbindingen (met name voor het ophalen van data) zullen vaker gelegd gaan worden via enkel een API Gateway en de inzet van de servicebus wordt teruggedrongen. Enkel op het gebied waar de huidige servicebus specifieke toegevoegde waarde levert, wordt deze voor overheden nog ingezet voor nieuwe verbindingen (eventueel in combinatie met een API Gateway). Dit zal naar verwachting voor overheden de meest voor de hand liggende oplossing zijn, gezien het huidige applicatielandschap. @@ -424,8 +425,6 @@ Toegevoegde waarde servicebus i.r.t. API-Gateway: - Orkestratie/logica - Gegevensautorisatie op doelbinding (bij gemeentelijke servicebussen vaak geïntegreerd) -> \*** Zie [StUF Berichtenstandaard - GEMMA Online](https://www.gemmaonline.nl/index.php/StUF_Berichtenstandaard) - ## Informatiemodel & API In dit hoofdstuk wordt ingegaan op de relatie tussen informatiemodel en API @@ -448,9 +447,9 @@ Een informatiemodel beschrijft een werkelijkheid. We onderscheiden vier niveaus De volgende begrippen worden gehanteerd in dit hoofdstuk: -- *Informatiemodel* : Niveau 3 - Logisch gegevensmodel / datamodel -- *Resource model* : Niveau 4 - Fysiek / technisch datamodel (directe datamodel van een API) -- *Applicatie data model* : Niveau 4 - Fysiek / technisch datamodel (datamodel van een achterliggend systeem) +- _Informatiemodel_ : Niveau 3 - Logisch gegevensmodel / datamodel +- _Resource model_ : Niveau 4 - Fysiek / technisch datamodel (directe datamodel van een API) +- _Applicatie data model_ : Niveau 4 - Fysiek / technisch datamodel (datamodel van een achterliggend systeem) ### API, Informatiemodel en Resource model @@ -486,7 +485,7 @@ Het Resource Model als logische view op achterliggende datamodellen heeft ook al ### Aanbevelingen -#### Verbindt het Resource Model met een Informatiemodel +#### Verbindt het Resource Model met een Informatiemodel Bij het aanbieden van data via een API is het van groot belang om de verbinding met een informatiemodel te hebben en deze verbinding ook te beschrijven en te publiceren bij de API documentatie. @@ -499,7 +498,7 @@ Het is echter belangrijk om de verbinding met een Niveau 3: - Logisch informatie ## API Security Architectuur -ICT beveiliging is over het algemeen gebaseerd op de aspecten *beschikbaarheid*, *integriteit* en *vertrouwelijkheid*. Dit hoofdstuk gaat allereerst in op deze drie aspecten en hun relaties met API beveiliging, waarna een aantal aan API beveiliging gerelateerde architectuurprincipes en architectuurpatronen zullen worden beschreven. +ICT beveiliging is over het algemeen gebaseerd op de aspecten _beschikbaarheid_, _integriteit_ en _vertrouwelijkheid_. Dit hoofdstuk gaat allereerst in op deze drie aspecten en hun relaties met API beveiliging, waarna een aantal aan API beveiliging gerelateerde architectuurprincipes en architectuurpatronen zullen worden beschreven. ### Beschikbaarheid @@ -507,7 +506,7 @@ Beschikbaarheid gaat erover om te allen tijde bij informatie en informatiebronne In de context van API's gaat beschikbaarheid erover dat consumenten van aangeboden API's juist worden geinformeerd over de afspraken omtrent (on)beschikbaarheid van de API's, dat de beschikbare capaciteit wordt verdeeld over de aangesloten API Clients en dat onvoorziene onbeschikbaarheid voor zowel aanbieders als consumenten van API's inzichtelijk wordt gemaakt, zodat daar juist op ingespeeld kan worden. -Aan beschikbaarheid gerelateerde API capabilities zijn *Caching*, *Rate limiting / Throttling*, *SLA Management*, *API Monitoring / Alerting* en *Foutafhandeling*. De onderstaande sectie *Componenten* beschrijft deze in meer detail en geeft aan waar deze worden toegepast in een API architectuur. +Aan beschikbaarheid gerelateerde API capabilities zijn _Caching_, _Rate limiting / Throttling_, _SLA Management_, _API Monitoring / Alerting_ en _Foutafhandeling_. De onderstaande sectie _Componenten_ beschrijft deze in meer detail en geeft aan waar deze worden toegepast in een API architectuur. ### Integriteit @@ -515,7 +514,7 @@ Integriteit gaat over het waarborgen van de integriteit van gegevens en systeemf In de context van API's gaat integriteit over het versleutelen en ondertekenen van berichten en gegevens, het "tamper-proof" maken van API's (API Hardening) middels validatie van API verzoeken en de vastlegging van de gegevensuitwisseling tussen API aanbieders en consumenten. -Aan integriteit gerelateerde API capabilities zijn *Logging / Audit Trail*, *Policy Enforcement*, *Identificatie / Authenticatie / Autorisatie* en *Sleutelbeheer*. De onderstaande sectie *Componenten* beschrijft deze in meer detail en geeft aan waar deze worden toegepast in een API architectuur. +Aan integriteit gerelateerde API capabilities zijn _Logging / Audit Trail_, _Policy Enforcement_, _Identificatie / Authenticatie / Autorisatie_ en _Sleutelbeheer_. De onderstaande sectie _Componenten_ beschrijft deze in meer detail en geeft aan waar deze worden toegepast in een API architectuur. ### Vertrouwelijkheid @@ -523,7 +522,7 @@ Vertrouwelijkheid gaat over het geheimhouden van gegevens en gegevensbronnen. Di In de context van API's gaat vertrouwelijkheid over het ervoor te zorgen dat tussen API aanbieder en consument uitgewisselde gegevens niet door onbevoegden kunnen worden ingezien en misbruikt. -Aan vertrouwelijkheid gerelateerde API capabilities zijn *Caching*, *Analytics*, *Logging / Audit Trail*, *Identificatie / Authenticatie / Autorisatie*, *Sleutelbeheer* en *Gebruiker / Rol beheer*. De onderstaande sectie *Componenten* beschrijft deze in meer detail en geeft aan waar deze worden toegepast in een API architectuur. +Aan vertrouwelijkheid gerelateerde API capabilities zijn _Caching_, _Analytics_, _Logging / Audit Trail_, _Identificatie / Authenticatie / Autorisatie_, _Sleutelbeheer_ en _Gebruiker / Rol beheer_. De onderstaande sectie _Componenten_ beschrijft deze in meer detail en geeft aan waar deze worden toegepast in een API architectuur. ### Standaard componenten @@ -550,8 +549,8 @@ Onderstaand overzicht beschrijft de componenten welke een rol spelen bij API bev - **Identity Provider:** Biedt de mogelijkheid aan eindgebruikers en Client applicaties om zichzelf te identificeren en Authentiseert deze. Geeft een authenticatie token af aan de Client applicatie waarmee deze API endpoints kan benaderen. In de context van OAuth wordt het component wat tokens uitgeeft vaak aangeduid als de **Authorization Server (AS)**. - **API Gateway:** De toegangspoort tot het achterliggende applicatie landschap. Alle API interactie verloopt via de API Gateway, waardoor de API Gateway een centrale rol heeft in de API beveiliging. Over het algemeen bevat de API Gateway een aantal traffic policies (zie volgend punt) welke bij elk API verzoek worden gevalideerd en voert de API Gateway initiële autorisatie van API verzoeken uit. Deze autorisatie omvat minimaal een controle of de ontvangen verzoeken van correcte Access Tokens zijn voorzien en kan eventueel role-based autorisaties toepassen. De API Gateway kan een verbinding met de Identity Provider hebben voor het geval door de Identity Provider afgegeven tokens onvoldoende informatie bevatten om autorisaties toe te passen. -- **Traffic Policies:** Een verzameling policies welke worden toegepast op al het API verkeer, of een specifiek deel daarvan. Voorbeelden zijn *Rate Limiting / Throttling*, *SLA Management* en *Input validatie*. Over het algemeen bieden API Gateways de mogelijkheden om traffic policies direct in te bouwen. -- **Gebruiker / client / rol beheer:** Het beheren van gebruikers van de API tooling, zoals beheerders, API developers en client developers, geregistreerde Client applicaties en een mapping van eindgebruikers identiteiten en rollen naar specifieke autorisaties. Dit is *niet* de identity store welke credentials van eindgebruikers bevat; dat gedeelte is de verantwoordelijkheid van de Identity Provider. +- **Traffic Policies:** Een verzameling policies welke worden toegepast op al het API verkeer, of een specifiek deel daarvan. Voorbeelden zijn _Rate Limiting / Throttling_, _SLA Management_ en _Input validatie_. Over het algemeen bieden API Gateways de mogelijkheden om traffic policies direct in te bouwen. +- **Gebruiker / client / rol beheer:** Het beheren van gebruikers van de API tooling, zoals beheerders, API developers en client developers, geregistreerde Client applicaties en een mapping van eindgebruikers identiteiten en rollen naar specifieke autorisaties. Dit is _niet_ de identity store welke credentials van eindgebruikers bevat; dat gedeelte is de verantwoordelijkheid van de Identity Provider. - **Sleutel beheer:** Beheert het sleutelmateriaal dat wordt gebruikt voor versleuteling en ondertekening van berichten welke worden uitgewisseld tussen API Gateway, Identity Provider en Client applicaties. - **Logging, Monitoring, Analytics, Caching:** Cross-cutting functionaliteiten welke op verschillende en/of meerdere plekken in het landschap geïmplementeerd kunnen worden. Voor al deze functionaliteiten is het van belang dat deze in lijn met AVG richtlijnen worden opgezet. Bij caching is het daarnaast belangrijk cache invalidaties te implementeren om te voorkomen dat verouderde cache data kan worden teruggehaald, zeker als daar privacy gevoelige informatie in kan staan. - **Back-end Services:** Applicaties die de daadwerkelijke resources implementeren. @@ -592,9 +591,9 @@ Door de toepassing van gedelegeerde identificatie en authenticatie in combinatie Voor gevallen dat het token onvoldoende informatie biedt om een autorisatie beslissing op te baseren, kan het benodigd zijn om token introspection toe te passen. In dit geval vraagt de API aanbieder op basis van het ontvangen token meer informatie over de geauthenticeerde gebruiker bij de Identity Provider. -Een belangrijk component bij autorisaties in de context van API's is de API Gateway. Op basis van een door de Identity Provider afgegeven access token kan de API Gateway beslissen of API aanroepen zijn toegestaan of niet. Hierbij kan de API Gateway *role-based access control (RBAC)* toepassen; *domein-specifieke autorisaties* worden over het algemeen toegepast door de back-ends om implementatie van business logica in de API Gateway te voorkomen. +Een belangrijk component bij autorisaties in de context van API's is de API Gateway. Op basis van een door de Identity Provider afgegeven access token kan de API Gateway beslissen of API aanroepen zijn toegestaan of niet. Hierbij kan de API Gateway _role-based access control (RBAC)_ toepassen; _domein-specifieke autorisaties_ worden over het algemeen toegepast door de back-ends om implementatie van business logica in de API Gateway te voorkomen. -Voor de implementatie van *domein-specifieke autorisaties* in de back-ends kunnen tevens microgateways of een service mesh oplossing worden gekozen. Bijkomend voordeel van het gebruik van een service mesh is dat deze standaard werken op basis van zero-trust networking. +Voor de implementatie van _domein-specifieke autorisaties_ in de back-ends kunnen tevens microgateways of een service mesh oplossing worden gekozen. Bijkomend voordeel van het gebruik van een service mesh is dat deze standaard werken op basis van zero-trust networking. #### Multi-level Authentication @@ -620,11 +619,11 @@ Het spreekt voor zich dat niet al deze security aspecten gestapeld moeten worden ## Verdieping Orkestratie -API orkestratie is een cruciaal concept binnen de moderne ICT-architectuur, vooral in de context van het integreren van verschillende applicaties en services. Het stelt organisaties in staat om complexe workflows te beheren door verschillende API's te coördineren en hun interacties te stroomlijnen. Dit biedt voordelen zoals verhoogde efficiëntie, verbeterde dataconsistentie en een betere gebruikerservaring. +API orkestratie is een cruciaal concept binnen de moderne ICT-architectuur, vooral in de context van het integreren van verschillende applicaties en services. Het stelt organisaties in staat om complexe workflows te beheren door verschillende API's te coördineren en hun interacties te stroomlijnen. Dit biedt voordelen zoals verhoogde efficiëntie, verbeterde dataconsistentie en een betere gebruikerservaring. ### Wat is API Orkestratie? -API orkestratie verwijst naar het proces waarbij meerdere API-aanroepen worden gecoördineerd om een specifieke taak of workflow uit te voeren. Dit kan bijvoorbeeld inhouden dat gegevens van verschillende bronnen worden samengevoegd of dat meerdere services in een bepaalde volgorde worden aangeroepen om een einddoel te bereiken. +API orkestratie verwijst naar het proces waarbij meerdere API-aanroepen worden gecoördineerd om een specifieke taak of workflow uit te voeren. Dit kan bijvoorbeeld inhouden dat gegevens van verschillende bronnen worden samengevoegd of dat meerdere services in een bepaalde volgorde worden aangeroepen om een einddoel te bereiken. ### Uitgangspunten @@ -661,18 +660,18 @@ Kadaster heeft in samenwerking met Geonovum het IMX initiatief gestart. Dit init ### Arazzo -De [Arazzo-specificatie](https://www.openapis.org/arazzo) is een nieuwe, door de gemeenschap gedreven standaard die is ontwikkeld onder het OpenAPI-initiatief, met als doel de documentatie en interactie van API's te verbeteren. Het biedt een **programmeertaal-onafhankelijk** kader om reeksen API-aanroepen en hun afhankelijkheden te definiëren, waardoor de communicatie van workflows duidelijker wordt. +De [Arazzo-specificatie](https://www.openapis.org/arazzo) is een nieuwe, door de gemeenschap gedreven standaard die is ontwikkeld onder het OpenAPI-initiatief, met als doel de documentatie en interactie van API's te verbeteren. Het biedt een **programmeertaal-onafhankelijk** kader om reeksen API-aanroepen en hun afhankelijkheden te definiëren, waardoor de communicatie van workflows duidelijker wordt. Dit project bevindt zich echter nog in een vroeg stadium. Ook is het maar de vraag in hoeverre (commerciële) software vendors erbij gebaat zouden zijn een dergelijke standaard te implenteren. Verder wordt de kanttekening geplaatst dat benodigde stappen bij orkestratie ook dynamisch kunnen worden berekend, zoals bij IMX wordt gedaan. In dat geval is het specificeren van een workflow niet relevant. #### Belangrijkste Kenmerken -- **Deterministische Workflows**: Arazzo maakt zowel menselijke leesbare als machine-leesbare documentatie mogelijk, wat de ervaring voor API-aanbieders en -gebruikers verbetert. +- **Deterministische Workflows**: Arazzo maakt zowel menselijke leesbare als machine-leesbare documentatie mogelijk, wat de ervaring voor API-aanbieders en -gebruikers verbetert. - **Toepassingen**: Interactieve workflowdocumentatie Automatische documentgeneratie Code- en SDK-generatie op basis van functionele gebruiksgevallen Automatisering van testgevallen en nalevingscontroles AI-gestuurde deterministische API-aanroep #### Relatie met OpenAPI -Arazzo aanvult de bestaande OpenAPI-specificatie door beschrijvingen van **groepen API's** en hun interacties mogelijk te maken, in plaats van alleen individuele API's. Deze bredere scope ondersteunt automatisering en codegeneratie, met als uiteindelijke doel de waarde die uit API's wordt gehaald te maximaliseren.Het project staat open voor deelname van de gemeenschap, met middelen beschikbaar op GitHub voor degenen die geïnteresseerd zijn in bijdragen of meer willen leren over de specificatie. +Arazzo aanvult de bestaande OpenAPI-specificatie door beschrijvingen van **groepen API's** en hun interacties mogelijk te maken, in plaats van alleen individuele API's. Deze bredere scope ondersteunt automatisering en codegeneratie, met als uiteindelijke doel de waarde die uit API's wordt gehaald te maximaliseren.Het project staat open voor deelname van de gemeenschap, met middelen beschikbaar op GitHub voor degenen die geïnteresseerd zijn in bijdragen of meer willen leren over de specificatie. ### Federatieve Toegangsverlening in combinatie met Orkestratie