diff --git a/API-strategie-best-practices/event-driven-architecture/abstract.md b/API-strategie-best-practices/event-driven-architecture/abstract.md new file mode 100644 index 00000000..96af2140 --- /dev/null +++ b/API-strategie-best-practices/event-driven-architecture/abstract.md @@ -0,0 +1,3 @@ +Deze Event Driven Architecture module beschrijft best practices voor het verwerken van Events in de context van APIs. + +De module is gebaseerd op de content van [de notificatieservices repository van VNG Realisatie](https://github.com/VNG-Realisatie/notificatieservices) en de overige bonnen zoals vermeld. diff --git a/API-strategie-best-practices/event-driven-architecture/eda_architecture_and_definitions.md b/API-strategie-best-practices/event-driven-architecture/eda_architecture_and_definitions.md new file mode 100644 index 00000000..3dbb380f --- /dev/null +++ b/API-strategie-best-practices/event-driven-architecture/eda_architecture_and_definitions.md @@ -0,0 +1,64 @@ +# Definities + +**Applicatie-event** : Iets dat binnen of buiten een applicatie is gebeurd en binnen die applicatie of daarbuiten gevolgen heeft. [bron](https://www.gemmaonline.nl/wiki/Id-9e48d727-8af0-4007-ac4e-5a27c0738f85) + +**Gebeurtenis** : Iets dat binnen of buiten een organisatie is gebeurd en binnen die organisatie of daarbuiten gevolgen heeft. [bron](https://www.gemmaonline.nl/wiki/Id-a79cbfcb-6c58-4793-9fc9-4401a4c7aaf7) + +**Notificatie** : Een bericht met als doel om iets of iemand ergens van op de hoogte te stellen. [bron](https://www.gemmaonline.nl/wiki/Id-08a2be25-75aa-4523-b29c-d4bfadeaa2cf) + +## Architectuur + +Event-driven architectuur (EDA) is een architectuurbenadering waarbij los gekoppelde componenten via 'events' informatie over plaatsgevonden gebeurtenissen met elkaar uitwisselen. Events fungeren daarbij vaak als trigger voor afnemers om in actie te komen. In business-termen spreken we over 'aanbieders' en 'afnemers' van events. Bij geautomatiseerde uitwisseling tussen applicaties gebruiken we de internationaal gangbare termen ‘producers’ voor applicaties die events publiceren, ‘consumers’ voor applicaties die events ontvangen en ‘intermediairs’ die verantwoordelijk zijn voor het distribueren van events naar consumers. + +EDA is geschikt om een robuuste en schaalbare architectuur te realiseren met dynamische en responsieve systemen. Het detecteren en reageren op gebeurtenissen staat daarbij centraal. Iets dat fundamenteel anders is dan bij gegevens- of proces-gerichte benaderingen. EDA vraagt om anders ontwerpen, realiseren en gebruiken van oplossingen. + +Het programma [Interbestuurlijke Datastrategie](https://www.digitaleoverheid.nl/interbestuurlijke-datastrategie/) probeert om beter gebruik te maken van beschikbare overheidsgegevens. Een van de verbeterpunten is om te zorgen dat als belangrijke gegevens wijzigen, dit via notificaties overal bekend wordt waar het van belang is. Om notificatieprocessen effectief en efficiënt te laten verlopen, is standaardisatie op verschillende vlakken nodig. Het [NL GOV profile for CloudEvents](https://www.logius.nl/domeinen/gegevensuitwisseling/nl-gov-profile-cloudevents/wat-nl-gov-profile-cloudevents) draagt hieraan bij door te standaardiseren hoe informatie over plaatsgevonden gebeurtenissen wordt uitgewisseld. + +Event-driven architectuur (EDA) is een architectuurbenadering waarbij systemen worden ontworpen om te reageren als zich bepaalde gebeurtenissen hebben voorgedaan. Om op de hoogte te zijn van veranderingen hoeven systemen niet steeds zelf gegevens op te vragen ('polling'), maar worden ze na een plaatsgevonden gebeurtenis daarvan op de hoogte gesteld. + +Een datarecord met gegevens over een plaatsgevonden gebeurtenis noemen we een 'event'. Events kunnen worden getransporteerd, opgeslagen en worden uitgewisseld tussen applicaties. Op basis van ontvangen events kunnen afnemende applicaties passende actie ondernemen. + +Belangrijke rollen bij EDA zijn: + +- **(Event)producers:** applicaties die informatie over plaatsgevonden gebeurtenissen publiceren. +- **Intermediairy:** applicaties die verantwoordelijk zijn voor het verstrekken van gepubliceerde events aan consumers. Producers en consumers communiceren niet direct met elkaar en hoeven, voor de distributie, elkaar niet te kennen. Voor invulling van deze rol wordt vaak gebruik gemaakt van speciale middleware-applicaties, zoals message- of event-brokers. +- **(Event)consumers:** applicaties die events ontvangen en er vervolgens op kunnen reageren. + +Onderstaand diagram toont hoe producers events publiceren en consumers events ontvangen. De rechterkant van het diagram toont de veelvoorkomende situatie met een Intermediairy. + +
+ +
Event Intermediairy
+
+ +### Meerwaarde + +EDA maakt een wendbare, modulaire aanpak mogelijk waarbij applicaties direct kunnen reageren op bepaalde gebeurtenissen. Dit leidt tot snellere en efficiëntere processen, beter gebruik van middelen en de mogelijkheid om systemen eenvoudig te schalen en uit te breiden. + +Door de flexibiliteit en modulariteit kunnen nieuwe diensten snel worden toegevoegd of aangepast, en kunnen applicaties beter samenwerken. Dit maakt betere dienstverlening mogelijk, kostenbesparingen en een grotere wendbaarheid van organisaties. + +EDA is vooral nuttig in situaties waar snelheid, flexibiliteit en efficiënte verwerking van gebeurtenissen van belangrijk zijn. Bijvoorbeeld bij industriële automatisering, Internet of Things (IoT) toepassingen, communicatie tussen microservices of bij het uitwisselen van informatie tussen overheidsorganisaties. + +### Soorten event-verwerking + +Afhankelijk van de doelen kan EDA verschillende manieren van event-verwerking ondersteunen, zoals: + +- **Zelfstandige gebeurtenissen verwerking**: Hierbij gaat het om gebeurtenissen die niet aan andere gebeurtenissen zijn gerelateerd en zelfstandig kunnen worden afgehandeld. Bijvoorbeeld een plaatsgevonden publicatie van een bericht op een social media platform. +- **Event-stream verwerking**: Hierbij is sprake van een stroom ('stream') aan gerelateerde events. Bij verwerking moet rekening worden gehouden met eerdere events. Bijvoorbeeld als het events betreft met informatie over de wijziging van een verblijfsadres van een persoon waarbij de volgorde van verwerking van belang is. +- **Complexe event verwerking**: hierbij kunnen op basis van een reeks events bepaalde patronen worden herkend. Bijvoorbeeld op basis van events afkomstig van een passantensensor signaleren dat zich te veel mensen in een gebiedszone bevinden. + +De thema-architectuur Eventoriëntatie van de GEMMA besteedt extra aandacht aan de functie 'notificeren'. Daarbij kan zowel sprake zijn van zelfstandig te verwerken events, als van gerelateerde events. + +### Begrippen + +EDA kent een aantal termen die te maken hebben met het ontwerpen, realiseren en werken met event-driven oplossingen. Hieronder staan een aantal veelgebruikte begrippen met hun betekenis: + +- **Change Data Capture**: Een techniek waarmee veranderingen in een database (zoals toevoegingen, verwijderingen en wijzigingen) in real-time worden vastgelegd en als event zijn te publiceren. +- **Messaging**: Een eenvoudige vorm van communicatie tussen systemen waarbij gegevens in de vorm van berichten worden uitgewisseld. Events worden vaak als bericht uitgewisseld. +- **Webhook**: Een mechanisme waarbij een applicatie een HTTP-verzoek (meestal een POST) naar een andere applicatie stuurt als er een bepaalde gebeurtenis heeft plaatsgevonden. +- **Event notificatie**: Een bericht met gegevens over een plaatsgevonden gebeurtenis, dat wordt verzonden naar geabonneerde applicaties. Binnen deze thema-[architectuur spreken we over 'notificeren' en 'notificaties'. +- **Event Carried State Transfer**: Een patroon waarbij events alle benodigde objectgegevens bevatten ('informatierijk'), zodat ontvangers (consumers) de actuele staat kunnen reconstrueren zonder opvragingen bij de bron te hoeven doen. +- **Event streaming**: Het continue genereren, verwerken en consumeren van een reeks gebeurtenissen ('stream') in real-time, voor grote dataverwerkings- en integratietaken. +- **Event processing**: Het interpreteren en verwerken van events voor een bepaald doel. Dat kan eenvoudig zijn (bijvoorbeeld filteren of routeren) of complex (bijvoorbeeld patroonherkenning binnen meerdere events). +- **Event sourcing**: Een patroon waarbij events onveranderlijk en duurzaam in een bronregister (‘event store’) worden vastgelegd en als authentieke bron worden beschouwd. De actuele staat van een object kan worden berekend door een reeks events opnieuw af te spelen. +- **Command/Query Responsibility Segregation**: Een patroon waarbij het verantwoordelijkheidsgebied voor het verwerken van commando's (wijzigen van data) wordt gescheiden van het uitvoeren van queries (lezen van data). Hiermee is de schaalbaarheid en flexibiliteit te vergroten. diff --git a/API-strategie-best-practices/event-driven-architecture/index.html b/API-strategie-best-practices/event-driven-architecture/index.html new file mode 100644 index 00000000..358d315d --- /dev/null +++ b/API-strategie-best-practices/event-driven-architecture/index.html @@ -0,0 +1,66 @@ + + + + + + + + + + + + Orchestration + + + + + +
+
+ +
+
+
+
+
+
+ + diff --git a/API-strategie-best-practices/event-driven-architecture/inleiding_eda.md b/API-strategie-best-practices/event-driven-architecture/inleiding_eda.md new file mode 100644 index 00000000..f33cce7c --- /dev/null +++ b/API-strategie-best-practices/event-driven-architecture/inleiding_eda.md @@ -0,0 +1,229 @@ +# Event Driven Architecture (EDA) introductie + +Deze handreiking bundelt de huidige content over Event Driven Architecture. Naast deze handreiking is het aan te bevelen om kennis te nemen van De bronnen bij Gemmaonline, de internationale cloudevents standaard, het Nederlandse profiel hierop en de bijbehorende guidelines. Zie ook de onderstaande Bronnen en verwijzingen + +## Bronnen en verwijzingen + +1. [Gemma Thema pagina Eventoriëntatie](https://www.gemmaonline.nl/wiki/Thema-architectuur_Eventorientatie) +2. [Logius Dienstverlening pagina NL GOV profile for Cloudevents](https://www.logius.nl/onze-dienstverlening/gegevensuitwisseling/nl-gov-profile-cloudevents/wat-nl-gov-profile-cloudevents) +3. [Eventoriëntatie introductie](https://www.gemmaonline.nl/wiki/Eventori%C3%ABntatie_introductie) +4. [Event-driven architectuur introductie](https://www.gemmaonline.nl/wiki/Event-driven_architectuur_introductie) +5. [Definiëren van gebeurtenistypes](https://www.gemmaonline.nl/wiki/Defini%C3%ABren_van_gebeurtenistypes) +6. [Uitdagingen en maatregelen](https://www.gemmaonline.nl/wiki/Uitdagingen_en_maatregelen) +7. [Cloudevents NL documentatie op Github](https://gitdocumentatie.logius.nl/publicatie/notificatieservices/CloudEvents-NL/) +8. [Internationale CloudEvents standaard](https://cloudevents.io/) +9. [NL GOV profile for CloudEvents](https://gitdocumentatie.logius.nl/publicatie/notificatieservices/cloudevents-nl/) +10. [Guidelines for NL-GOV profile CloudEvents (Handreiking)](https://gitdocumentatie.logius.nl/publicatie/notificatieservices/guidelines/) + +## Eventoriëntatie introductie + +Eventoriëntatie is een benadering waarbij gebeurtenissen centraal staan en systemen gebeurtenisgedreven ('event-driven') werken. Event driven architectuur (EDA) is de architectuurstijl die hierbij past. EDA kent eigen uitgangspunten en patronen en leidt tot systemen waarin los gekoppelde applicaties informatie over plaatsgevonden gebeurtenissen met elkaar uitwisselen. + +### Events + +In lijn met internationale standaarden gebruiken we de term 'event' als aanduiding voor een datarecord met gegevens over een plaatsgevonden gebeurtenis. Events zijn onder andere te gebruiken voor: + +- **publiceren** (bijvoorbeeld een event met informatie over een naamswijziging) +- **filteren** (bijvoorbeeld door events op basis van een selectiecriterium te selecteren) +- **routeren** (bijvoorbeeld door events op basis van een kenmerk naar de juiste bestemming te sturen) +- **verstrekken** (bijvoorbeeld door een event naar een afnemende applicatie te sturen) +- **bewaren** (bijvoorbeeld door gepubliceerde events in een registratie vast te leggen). + +#### Architectuur van gebeurtenissen + +Werken met events vereist een architectuur die hier op is ingericht: event-driven architectuur. Binnen dit type architectuur draait het om gebeurtenissen die zaken in gang zetten. Na het plaatsvinden van een gebeurtenis worden events geproduceerd door '(event)producers' en, al dan niet via een 'intermediair', verstrekt aan '(event)consumers'. Event-driven architectuur introductie licht toe wat kenmerkend is voor dit type architectuur. + +#### Architectuur van notificaties + +Met 'notificeren' bedoelen we het via events ('notificaties') op de hoogte stellen van applicaties dat er een bepaalde gebeurtenis heeft plaatsgevonden. Notificeren is een voorbeeld van het werken met events. Voor overheidsorganisaties is het belangrijk om anderen te notificeren als er belangrijke gebeurtenissen hebben plaatsgevonden en is het belangrijk om op de hoogte te worden gesteld als er elders relevante gebeurtenissen hebben plaatsgevonden. Notificeren krijgt momenteel veel aandacht binnen de overheid, maar is zeker niet het enige doel van event-driven werken. + +### Standaardisatie + +Events kunnen gegevens over allerlei soorten plaatsgevonden gebeurtenissen bevatten. Het kan bijvoorbeeld gaan om een muisklik door een gebruiker, een door een sensor geregistreerde waarde, een ontvangen betaling, een voltrokken huwelijk of een plaatsgevonden gegevensmutatie. Het is cruciaal dat ieder type gebeurtenis nauwkeurig worden beschreven (zie ook [[[#definiëren-van-gebeurtenistypes]]]). Om effectief met events te kunnen werken moeten beschrijvende gegevens gestandaardiseerd worden vastgelegd. Voor dit doel is [de internationale CloudEvents standaard](https://cloudevents.io/) ontwikkeld. Het [NL GOV profile for CloudEvents](https://gitdocumentatie.logius.nl/publicatie/notificatieservices/cloudevents-nl/) bouwt hierop voort en bevat afspraken over gebruik van de standaard binnen de Nederlandse overheid. + +#### Voordelen van Eventoriëntatie + +Eventoriëntatie kan belangrijke voordelen opleveren, zoals: + +- **Snelle reacties:** door snel te notificeren kunnen consumers tijdig en proactief reageren op veranderingen. Dit leidt tot betere dienstverlening en het voorkomen van vervelende situaties door het werken met verouderde en foutieve gegevens. +- **Effectiviteit:** organisaties kunnen beschikken over actuele en goed te interpreteren gegevens. Dit maakt betere besluitvorming mogelijk. +- **Inzicht:** doorlopend beschikken over actuele informatie maakt realtime analyses en voorspellingen mogelijk. Bijvoorbeeld om proactieve maatregelen te nemen. +- **Robuustheid en Schaalbaarheid:** door de ontkoppeling van producers en consumers zijn systemen robuust en goed op te schalen. +- **Flexibiliteit:** veranderingen zoals het toevoegen van nieuwe consumers is eenvoudig mogelijk. + +#### Meerwaarde voor overheden + +Voor overheden geldt dat zij voor het uitvoeren van haar taken over betrouwbare gegevens moet kunnen beschikken. Daarvoor is het nodig om tijdig op de hoogte te zijn wanneer zich bepaalde gebeurtenissen hebben voorgedaan. Daarbij kan het gaan om gebeurtenissen binnen de eigen organisatie (bijvoorbeeld een plaatsgevonden verhuizing van een inwoner die ook een uitkering krijgt) of om elders plaatsgevonden gebeurtenissen (bijvoorbeeld een inschrijving bij de Kamer van Koophandel van bedrijf binnen de gemeente). + +Gemeenten werken met gegevens en processen die snel kunnen veranderen, zoals aanvragen van vergunningen, meldingen van bewoners, of het beheren van infrastructuur zoals verkeer en afvalinzameling. Event Driven Architecture stelt overheden in staat om wendbaarder, efficiënter en responsiever te zijn in hun dienstverlening en betere service aan burgers en bedrijven te bieden. Bijvoorbeeld door snel gepersonaliseerde dienstverlening, zoals het automatisch versturen van meldingen of proactief aanbieden van gemeentelijke diensten wanneer relevante gebeurtenissen optreden, zoals het bijna verlopen van een paspoort. + +Gemeenten werken vaak samen met externe partijen, zoals waterschappen, vervoersbedrijven of andere overheden. Event Driven Architecture maakt het gemakkelijker om systemen van verschillende organisaties op elkaar aan te sluiten en gebeurtenisgegevens te delen, wat samenwerking en coördinatie verbetert. Om vaker als **'1 overheid'** naar buiten te kunnen treden en proactief diensten te leveren richting burgers en bedrijven (“van aanvragen, naar aanbieden”) moeten overheidsorganisaties elkaar vaker en sneller informeren over plaatsgevonden gebeurtenissen. Bijvoorbeeld bij plaatsgevonden levensgebeurtenissen, zoals een kind krijgen, gaan studeren of overlijden. + +Het uitgangspunt **“van aanvragen, naar aanbieden”** kan ook toegepast worden op het uitwisselen van gegevens tussen organisaties. Bijvoorbeeld waar het gaat om eenmalig vastgelegde brongegevens (**'data bij de bron'**). Voor afnemers daarvan volstaat het kunnen opvragen daarvan vaak niet om bedrijfsprocessen verantwoord uit te kunnen voeren. Wanneer eerder opgevraagde gegevens door een gebeurtenis zijn gewijzigd moet dit snel bekend worden gemaakt om te voorkomen dat te nemen besluiten op verouderde gegevens zijn gebaseerd. + +### Paradigmaverschuiving (“van aanvragen, naar aanbieden”) + +Eventoriëntatie verschilt in een aantal opzichten fundamenteel van andere benaderingen. In plaats van synchroon en procedureel denken, moet er bijvoorbeeld meer dynamisch en asynchroon worden gedacht. De praktijk leert dat zo'n paradigma-verandering niet vanzelf gaat. Naast technische maatregelen moet daarom ook worden gezorgd voor voldoende kennis. Uitdagingen en maatregelen beschrijft in welke opzichten eventoriëntatie wezenlijk verschilt van andere benaderingen en wat bij toepassing ervan uitdagingen en mogelijke maatregelen zijn. + +## Aanleiding + +De hoeveelheid data die elke dag wordt geproduceerd, groeit exponentieel. Of die data nu bestaat uit updates van sensoren, klikken op een website of wijzigingen binnen elders beheerde brongegevens, van applicaties wordt verwacht dat ze deze stroom van informatie tijdig verwerken. Om dat mogelijk te maken moet informatie over relevante plaatsgevonden gebeurtenissen tijdig geautomatiseerd worden verstrekt aan partijen die daar belang bij hebben. + +Gemeenten werken steeds meer in gedistribueerde omgevingen, waar gegevens op verschillende plaatsen worden vastgelegd. De afgelopen jaren is veel energie gestoken in het toegankelijk maken van gegevens in bronregistraties via **Application Programming Interfaces (API's)**. Om tijdig en adequaat diensten te kunnen leveren, volstaat opvragen van brongegevens vaak niet. Bij veel bedrijfsprocessen moeten afnemers op de hoogte worden gesteld als brongegevens wijzigen, zodat zij er snel en adequaat op kunnen reageren. + +> "Veel organisaties zijn afhankelijk van de gegevens van anderen, hebben hun handen vol aan het verkrijgen hiervan en kunnen daar in veel gevallen niet snel genoeg over beschikken. Hoe meer up-to-date de IT van de overheid, hoe groter de mogelijkheden om als overheid proactief en responsief op te treden. En hoe effectiever gegevensuitwisseling, hoe beter professionals in de uitvoering gefundeerde besluiten kunnen nemen." - _Bron: Staat van de Uitvoering 2024_ + +## Doel + +‘Eventoriëntatie" heeft als doel om overheden en leveranciers te ondersteunen bij het ontwerpen, realiseren en gebruiken van (meer) event-georiënteerde oplossingen. Werken met events vereist specifieke afspraken, standaarden en voorzieningen. Maar het vereist zeker ook een andere mindset om vraagstukken event-gericht in plaats van proces- of gegevensgericht te benaderen. Waar we het als consument al heel normaal vinden dat we via de smartphone snel op de hoogte worden gebracht als een besteld artikel is verzonden, is elkaar informeren over belangrijke gebeurtenissen binnen de overheid nog geen vanzelfsprekendheid. + +Bij 'gebeurtenissen' kan het om allerlei soorten gebeurtenissen gaan. Bijvoorbeeld om 'discrete gebeurtenissen', die op een specifiek moment in de tijd plaatsvinden (bijvoorbeeld een sensor die een meting heeft verricht of een boete die is opgelegd). 'Statusveranderingen' waarbij de toestand van een object wijzigt (bijvoorbeeld de huwelijkse staat van een persoon), of ['levensgebeurtenissen'](https://www.rijksoverheid.nl/onderwerpen/levensgebeurtenissen/overzicht-levensgebeurtenissen) die van belang zijn voor meerdere overheidsorganisaties (bijvoorbeeld met pensioen gaan of verhuizen). + +Eventoriëntatie is voor verschillende doelen bruikbaar. Het volgende hoofdstuk [[[#notificeren-introductie]]] besteedt extra aandacht aan 'notificeren': het geautomatiseerd verstrekken van informatie over plaatsgevonden gebeurtenissen aan applicaties die daar belang bij hebben. Binnen de Nederlandse overheid komt steeds meer behoefte aan notificeren. Onder andere om proactieve dienstverlening te bieden en om verantwoord gebruik te maken van elders beheerde brongegevens. + +## Uitdagingen en maatregelen + +Een event georiënteerde benadering wijkt in een aantal opzichten af van bijvoorbeeld een gegevens- of procesgerichte benadering. Onderstaande tabel toont aspecten waarop oplossingen die vooral met het request-response patroon werken, verschillen van event-driven oplossingen. + +| **Aspect** | **Request-response patroon** | **Event-driven patroon** | +| --------------- | ------------------------------------------------------------------- | ----------------------------------------------------- | +| Communicatie | 1-weg (van A naar B) | 2-weg (van A naar B en B naar A) | +| Koppeling | Sterk gekoppeld (afhankelijk van elkaar) | Los gekoppeld (onafhankelijk van elkaar) | +| Tijdigheid | Synchroon (A wacht op verwerking en resultaat van B) | Veelal asynchroon (A wacht niet op verwerking door B) | +| Schaalbaarheid | Moeilijker schaalbaar (B krijgt het drukkers als aantal A’s groeit) | Makkelijk schaalbaar (via toevoegen nieuwe consumers) | +| Consistentie | Strong consistentie (altijd consistent) | Eventual consistency (tijdelijk niet consistent) | +| Foutafhandeling | Eenvoudig (door synchroniciteit) | Complex (door a-synchroniciteit) | + +### Uitdagingen + +Realiseren van event-driven oplossingen brengt een aantal uitdagingen met zich mee. Bij het ontwerpen en realiseren van oplossingen moet daar rekening mee worden gehouden om te voorkomen dat er in de praktijk problemen optreden. + +- **Complexiteit in architectuur en beheer:** Events worden vaak gebruikt om informatie uit te wisselen tussen applicaties in gedistribueerde omgevingen. Naarmate het aantal events en applicaties toeneemt, wordt lastig om overzicht te houden over aan wie, wanneer, welke events zijn verstrekt. Dit kan leiden tot fouten of inconsistenties. +- **Debuggen en foutafhandeling:** Het debuggen van event-driven systemen kan lastig zijn omdat events vaak asynchroon worden verwerkt. Het is moeilijker om de exacte volgorde van events te bepalen en te analyseren wat er precies gebeurd tijdens verwerking. +- **Foutafhandeling:** Wanneer er fouten optreden moeten die goed worden afgehandeld. Een van de risico's als dit niet gebeurd, is dat events vaker worden verstrekt of, erger nog, verloren gaan en afnemers nooit bereiken. +- **Volgordelijkheid:** Het kan belangrijk zijn dat afnemers events in de juiste volgorde ontvangen. Bijvoorbeeld bij applicaties waar de volgorde belangrijk is, zoals financiële of administratieve systemen. +- **Inconsistentie:** Mede door het asynchroon verwerken van events, kunnen gegevens tijdelijk inconsistent zijn. Na verloop van tijd moeten gegevens weer consistent zijn ('eventual consistency'). +- **Correcties:** Wanneer aanbieders fouten maken en die later corrigeren, ontvangen afnemers eerst een event met foutieve informatie en daarna een event met de juiste informatie. +- **compenserende transactie:** Afnemers moeten rekening houden met de mogelijkheid dat een event foutieve informatie kan bevatten. Bijvoorbeeld door eerst een periode te wachten voor een kritische transactie wordt uitgevoerd of door een compenserende transactie uit te voeren als later een event met gecorrigeerde gegevens volgt. +- **Vertraging:** event-driven systemen moeten snelle verwerking van informatie ondersteunen. Maar er kan soms vertraging optreden bij het uitwisselen van events. Dit kan een negatieve invloed hebben op de reactietijd van het systeem of, bij samenwerking tussen meerdere applicaties, tot inconsistenties. +- **Overbelasting:** Een plotselinge stroom van events kan leiden tot overbelasting van applicaties. Event-verstrekking moet in die gevallen tijdelijk kunnen worden vertraagd ('throttling'). +- **Systeemaanpassingen:** Veel bestaande (legacy)systemen werken gegevens-georiënteerd. Het aanpassen van deze systemen om events te kunnen verwerken kost tijd en geld. +- **Monitoring en auditing:** Continu monitoren is ingewikkelder bij gedistribueerde systemen en gebeurtenissen die asynchroon worden verwerkt. Dit kan auditing en logging uitdagend maken, vooral als er een nauwkeurige audit trail nodig is. + +### Maatregelen + +Om aanwezige uitdagingen het hoofd te bieden zijn verschillende soorten maatregelen mogelijk. Hieronder worden een aantal te treffen maatregelen beschreven. + +- **Kennis opdoen:** Zorg voor kennis van event-driven architectuur. Zonder voldoende kennis is er een (te) groot risico dat projecten niet succesvol verlopen. Onder andere binnen de financiële en logistieke sector is al veel ervaring opgedaan met event georiënteerd werken en zijn er best practices waar gebruik van kan worden gemaakt. EDA is vaak onderdeel van een API First aanpak en daarom ook onderdeel van het [Kennisplatform API's](https://developer.overheid.nl/communities/kennisplatform-apis/). +- **Consistentie borgen:** Pas mechanismen toe om events altijd in de juiste volgorde te verwerken. Bijvoorbeeld via versienummering, timestamping en het gebruik van vaker uit te voeren (idempotente) operaties. Als er tijdelijk inconsistenties kunnen zijn, moet hier bij verwerking rekening mee worden gehouden. +- **Betrouwbaarheid verbeteren:** Gebruik specialistische (middleware)applicaties die de benodigde complexe technische functionaliteit bieden. Bijvoorbeeld voor message queues waarmee events kunnen worden opgeslagen voordat ze worden verwerkt, retry-mechanismen die zorgen voor automatische her-verzending van events na verstoringen of fouten en dead-letter queues om events die niet zijn te verwerken te bewaren voor later onderzoek en afhandeling, rate limiting en throttling om het aantal events dat per seconde wordt verstrekt te beperken. Veelal zijn deze functionaliteiten standaard beschikbaar in API-Gateway's, [zie ook de referentiecomponenten in de NL API Strategie architectuur](https://geonovum.github.io/KP-APIs/API-strategie-algemeen/Architectuur/#referentiecomponenten). +- **Inzicht en robuustheid verbeteren:** Gebruik gespecialiseerde systeemtools, zoals monitoringtools voor continu toezicht op de verwerking van gebeurtenissen, logging tools voor voor uitgebreide logging van verwerking, 'circuit breakers' die zorgen dat bij disfunctioneren van een bepaalde component de rest van het systeem blijft werken, tracing om de volledige reis van een event te kunnen volgen. +- **Events aggregeren:** Aggregeer veel kleine, snel opeenvolgende events zodat het aantal verstrekkingen naar afnemers beperkt blijft. Hierdoor blijft het aantal event en de bijbehorende systeembelasting beperkt. + +### implicaties + +Event-georiënteerde oplossingen kunnen grote voordelen bieden, maar zijn niet altijd eenvoudig te realiseren. Net zoals bij andersoortige oplossingen moet rekening worden gehouden met de omstandigheden waarbinnen een toepassing moet werken. Welke mogelijkheden hebben betrokken organisaties en applicaties? Wat voor onvoorziene omstandigheden kunnen zich voordoen? Hoe erg is het als er bepaalde fouten optreden? Antwoorden op dit soort vragen bepalen sterk mee of en hoe event-driven oplossingen geschikt zijn. + +## Definiëren van gebeurtenistypes + +Om effectief notificeren mogelijk te maken is een van de eerste stappen het onderkennen van belangrijke gebeurtenissen die binnen het domein van een publisher plaatsvinden. +Het onderkennen van de gebeurtenissen, en daarmee inspelen op de gebruikerswensen sluit aan bij de [NL API Strategie - gebruikerswensen](https://geonovum.github.io/KP-APIs/API-strategie-algemeen/Gebruikerswensen/). +Hieronder staat een 3-staps aanpak voor het bepalen en beschrijven van gebeurtenistypes waarvoor notificaties verstrekt gaan worden. + +### Stap 1: Inventariseren van gebeurtenissen + +De eerste stap is het identificeren van plaatsvindende gebeurtenissen binnen het domein, of een deel daarvan, bij de aanbieder. Daarbij is onderscheid te maken in + +- 'business gebeurtenissen' die herkenbaar zijn voor zakelijke vertegenwoordigers, zoals 'Offerte ontvangen' of 'Factuur betaald', ,en +- 'technische gebeurtenissen' die herkenbaar zijn voor IT'ers, zoals 'Gebouwgegevens gewijzigd' of 'Klantrecord toegevoegd'. + +Vanwege de bredere herkenbaarheid is het meestal wenselijk om gebeurtenissen uit de eerste categorie te bepalen, maar in bepaalde gevallen kunnen ook meer technische gebeurtenissen meerwaarde hebben. Hierbij kan gebruik worden gemaakt van een techniek als '[event storming]' waarbij via workshops alle gebeurtenissen die binnen een specifiek domein worden geïnventariseerd en geordend. + +### Stap 2: Bepalen van relevante gebeurtenistypes + +Bij deze stap wordt bepaald welke soorten gebeurtenissen het meest relevant zijn voor derden om notificaties over te ontvangen. Hierbij is het van belang dat consumers hun wensen kunnen inbrengen op basis waarvan een producer kan besluiten voor welke gebeurtenistypes hij events gaat publiceren. Ook bij deze stap is het van belang dat zowel domein-experts als technici zijn vertegenwoordigd en zij zoveel mogelijk dezelfde taal spreken. + +### Stap 3: Documenteren van gebeurtenistypes + +De laatste stap is het gedetailleerd beschrijven van de benoemde soorten gebeurtenissen. Dit omvat het definiëren van algemene kenmerken zoals de naam, korte omschrijving, en specifieke attributen die altijd aanwezig moeten zijn in notificaties. Het belang van een goede beschrijving is groot, omdat consumers verstrekte notificaties correct moeten interpreteren en op basis daarvan gaan verwerken. Bij voorkeur is de betekenis van de gebeurtenistypes zodanig vastgelegd dat hij opvraagbaar is voor zowel mensen als applicaties. + +## De CloudEvents standaard + +CloudEvents is een open standaard voor het beschrijven van gebeurtenisgegevens. Het doel van deze standaard is om de interoperabiliteit tussen verschillende diensten en platforms te verbeteren door informatie over plaatsgevonden gebeurtenissen ('events') op een gestandaardiseerde manier uit te wisselen. Dit maakt het eenvoudiger om na het optreden van een gebeurtenis met elkaar te communiceren. Het doel is om interoperabiliteit en consistentie in event-driven omgevingen te bevorderen. + +Kenmerken van de standaard zijn: + +- Gestandaardiseerd formaat: CloudEvents definieert een minimaal formaat voor metagegevens over een gebeurtenis (bijvoorbeeld tijdstempel, bron, type). Waar nodig kunnen uitbreidingen ('extensies') op de basisstructuur worden gedefinieerd. +- Techniek-neutraal: De standaard is ontworpen om te werken met verschillende gegevensformaten (bijvoorbeeld JSON en XML) en transportprotocollen (bijvoorbeeld HTTP en AMQP). Gebruikers houden hierdoor de vrijheid om gebruik te maken van technologie waarmee zij vertrouwd zijn. +- Inhoud-onafhankelijk: de standaard definieert uitsluitend de meta-[informatie om gebeurtenissen te beschrijven en legt geen beperkingen op aan de voor consumers bestemde inhoud ('payload') van een event. +- Modulaire opbouw: De standaard kent een basis-specificatie en aanvullend daarop specificaties voor gebruik bij verschillende formaten en protocollen. + +### Status + +CloudEvents is gestart om te komen tot een standaard voor het gestandaardiseerd beschrijven van gebeurtenisgegevens binnen cloud gebaseerde systemen. De standaard is echter ook bij andere soorten systemen bruikbaar. CloudEvents is in 2018 geaccepteerd door de [Cloud Native Computing Foundation](https://www.cncf.io/). De standaard kreeg in 2019 het volwassenheidsniveau 'Incubating'. In 2024 is het hoogste volwassenheidsniveau '[Graduated](https://www.cncf.io/projects/cloudevents/)' bereikt. De standaard wordt door steeds meer leveranciers ondersteund. + +Het [NL GOV profile for CloudEvents](https://www.logius.nl/domeinen/gegevensuitwisseling/nl-gov-profile-cloudevents) is ontwikkeld voor gebruik binnen de Nederlandse overheid. Het profiel voegt een aantal binnen de overheid geldende afspraken toe aan de CloudEvents-specificatie. Het profiel is in beheer bij Logius en nu in behandeling bij het Forum Standaardisatie om te worden toegevoegd aan de [pas-toe-of-leg-uit lijst met open standaarden](https://www.forumstandaardisatie.nl/open-standaarden). + +### Inhoud + +Binnen CloudEvents wordt onder een 'event' een datarecord met gegevens over een plaatsgevonden gebeurtenis verstaan. De CloudEvents Core Specificatie beschrijft de meest voorkomende event-attributen: + +- Context attributen: een beperkte set verplichte en optionele attributen om een gebeurtenis te beschrijven: + - **ID** (verplicht): Een unieke identifier voor het event. + - **Source** (verplicht): De bron van het event (bijv. het systeem of de service die het event genereert). + - **Type** (verplicht): Het type van het event (bijv. "bestelling geplaatst"). + - **Specversion** (verplicht): De versie van de CloudEvents specificatie die wordt gebruikt. + - **Time** (optioneel): Het tijdstip waarop het event is gegenereerd. + - **Contenttype** (optioneel): Het type van de data-payload (bijv. application/json). + - **Data** (optioneel): De daadwerkelijke inhoud van het event (payload) met voor afnemers bestemde domeinspecifieke informatie over de plaatsgevonden gebeurtenis. Er zijn geen beperkingen qua structuur en formaat van opgenomen gegevens. +- Aanvullende attributen (optioneel): zelf te definiëren kenmerken die nodig zijn binnen specifieke toepassingen of domeinen. + +### Voorbeeld + +Onderstaand voorbeeld toont een bericht in JSON-formaat dat voldoet aan de CloudEvents standaard. Het bericht is een voorbeeld van een event dat bruikbaar is om applicaties te notificeren dat een bepaalde gebeurtenis heeft plaatsgevonden (in dit geval een verhuizing van een persoon). + +```json +{ + "id": "6a6800cc-5d30-42d2-9078-cf28fd038e58", + "source": "urn:nld:oin:00000001823288444000:systeem:BRP-component", + "specversion": "1.0", + "type": "nl.brp.persoon-verhuisd", + "time": "2021-10-27T14:35:00.042Z", + "prioriteit": "hoog", + "datacontenttype": "application/json", + "data": { + "abonnementId": "d7c5fc0a-f7c9-4376-b54a-32df4756059e", + "bsn": "012345678" + } +} +``` + +## NL GOV Profile for CloudEvents introductie + +Het NL GOV profile for CloudEvents is een profiel met een aantal Nederlandse afspraken over het gebruik van de internationale standaard CloudEvents. + +### Afspraken + +Gestandaardiseerde metadata voor events, zoals om wat voor soort event het gaat en waar het vandaan komt, maakt uitwisseling en gebruik van events eenvoudiger. + +CloudEvents heeft als doel om het beschrijven van plaatsgevonden gebeurtenissen te standaardiseren via een beperkte set afgesproken metadata. CloudEvents is als standaard breed toepasbaar en bruikbaar bij verwerking binnen verschillende services, platforms en infrastructuren. + +Het NL GOV profile for CloudEvents heeft als doel om binnen de Nederlandse overheid optimaal gebruik te maken van de CloudEvents-standaard. Het profiel bevat aanvullende afspraken over het gebruik van CloudEvents door overheidsorganisaties. Bijvoorbeeld afspraken over hoe bepaalde door CloudEvents voorgeschreven attributen moeten worden gebruikt, zoals: + +- 'id' om over een unieke identificatie voor events te beschikken. +- 'type' om te beschrijven om wat voor soort gebeurtenis het gaat. +- 'source' om te beschrijven uit welke bron een event afkomstig is. + +Internationale standaardisatie vormt zo de basis, die wordt aangevuld met afspraken die binnen de Nederlandse context nodig of wenselijk zijn. + +### Gebruik + +CloudEvents kent een gelaagde architectuur. De kern wordt gevormd door de ['CloudEvents core specificatie'](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md), waar het NL GOV profiel op voortbouwt. Maar de CloudEvents-community heeft ook aanvullende producten gemaakt. Daarin staan afspraken over hoe de core specificatie moet worden gebruikt wanneer bepaalde technologie wordt toegepast. Daarbij kan het gaan om bepaalde gegevensformaten (bijvoorbeeld JSON of XML) of om bepaalde transportprotocollen (bijvoorbeeld HTTP, AMQP of AVRO). Doel hiervan is om gebruik in de praktijk maximaal te standaardiseren. + +In lijn met de gelaagde CloudEvents-architectuur zijn als aanvulling op het NL GOV profiel [Guidelines for NL-GOV profileCloudEvents](https://gitdocumentatie.logius.nl/publicatie/notificatieservices/guidelines/) gepubliceerd. De guidelines zijn te zien als handreiking voor toepassing van het NL GOV profiel bij gebruik van van bepaalde technologie. Aansluitend bij de actuele behoeften binnen de Nederlandse overheid gaat het daarbij om het protocol HTTP, het gegevensformaat JSON en het vaak toegepaste patroon Webhook. + +### Status en governance + +Het NL GOV Profile for CloudEvents wordt beheerd en doorontwikkeld door de afdeling Standaarden van Logius. Aan het door Logius georganiseerde Technisch Overleg Notificeren nemen verschillende overheidsorganisaties deel en worden wensen en vragen met betrekking tot de standaard besproken. Het NL GOV Profile for CloudEvents is voorgedragen bij het Forum voor Standaardisatie voor opname op de overheidsbrede pas-toe-of-leg-uit lijst van open standaarden. + +Gemeenten kennen sinds enkele jaren een notificatiestandaard, bedoeld voor ondersteuning van zaakgericht werken. De VNG heeft als doel om die standaard op termijn breder toepasbaar te maken dan alleen voor zaakgericht werken. Los van het wel of niet opnemen op de lijst van open standaarden zal het NL GOV Profile for CloudEvents daarbij een belangrijke rol spelen. Gemeenten hebben immers veel belang bij het gestandaardiseerd kunnen uitwisselen van events met andere overheidsorganisaties. Binnen een eerder uitgevoerde pilot is vastgesteld dat de huidige notificatiestandaard voor zaakgericht werken relatief eenvoudig is door te ontwikkelen, om te kunnen voldoen aan het NL GOV Profile for CloudEvents. diff --git a/API-strategie-best-practices/event-driven-architecture/inleiding_notificeren.md b/API-strategie-best-practices/event-driven-architecture/inleiding_notificeren.md new file mode 100644 index 00000000..37aa88d5 --- /dev/null +++ b/API-strategie-best-practices/event-driven-architecture/inleiding_notificeren.md @@ -0,0 +1,161 @@ +# Notificeren introductie + +"Notificeren" betekent iemand of iets via een bericht op de hoogte brengen van iets. De term wordt vaak gebruikt om aan te geven dat iemand officieel geïnformeerd wordt over een bepaalde gebeurtenis of verplichting. In digitale context betekent het vaak dat een applicatie een melding stuurt aan een gebruiker of aan een andere applicatie. Bijvoorbeeld wanneer er een nieuw bericht is ontvangen en dit aan een gebruiker of een applicatie wordt meegedeeld. Notificeren is een belangrijk onderdeel van een event-georiënteerde aanpak, waarbij systemen of mensen direct geïnformeerd worden wanneer er iets gebeurt dat relevant is voor hen. Het stelt hen in de gelegenheid om proactief of reactief passende actie te ondernemen. + +Een belangrijke onderdeel van het [project Omnichannel](https://www.gemmaonline.nl/wiki/Project_omnichannel) is het notificeren van burgers, waarbij op de achtergrond ook notificaties tussen applicaties een rol spelen. Gemeenten sturen notificaties om hun dienstverlening klantvriendelijker te maken. Ontwikkelingen zoals de Wet modernisering elektronisch bestuurlijk verkeer (Wmebv) maken het bovendien steeds vaker verplicht om burgers te informeren. Bijvoorbeeld wanneer er nieuwe formele berichten beschikbaar zijn, zoals een besluit. Daardoor worden effectieve notificatievoorzieningen voor gemeenten steeds belangrijker, wat vraagt om een ondersteunende informatievoorziening die hierop goed is afgestemd. + +> [Zie ook de animatie op YouTube die hierover door de VNG is gemaakt.](https://youtu.be/AVGwTXzyCjk) + +## Notificaties + +Met een 'notificatie' bedoelen het bericht met gegevens die bij notificeren worden verstrekt. Een notificatie kan allerlei soorten informatie bevatten. Op basis van de opgenomen informatie is onderscheid te maken in notificaties over een: + +- **'Seintje':** er wordt een signaal afgegeven wanneer er iets is gebeurd. Deze vorm van notificatie is gebruikelijk in de wereld van sensoren (IoT), maar komt minder vaak voor binnen administratieve omgevingen. +- **Gegevensmutatie:** deze notificaties zijn gericht op het doorgeven van oude en nieuwe gegevens na een verandering ('was-wordt'). De aanleiding en context ontbreekt vaak, waardoor de gebruiker zelf moet afleiden welke gebeurtenis er heeft plaatsgevonden. Dit kan leiden tot foute conclusies en onjuiste acties. +- **Gegevensmutatie + Aanleiding:** naast de gegevensmutatie wordt ook de aanleiding voor de gebeurtenis meegegeven. Gebruikers begrijpen beter wat er precies is gebeurd en kunnen er beter op reageren. +- **Gebeurtenis + Gegevens:** In plaats van een aantal 'was-wordt gegevens' worden relevante gegevens over de plaatsgevonden gebeurtenis verstrekt. Afnemers weten op basis hiervan precies wat er is gebeurd. Als alle relevante gegevens zijn verstrekt ('informatierijke notificatie') kunnen consumers daarmee passende actie(s) uitvoeren. +- **Gebeurtenis + Identificatie:** Bij zo'n 'informatiearme notificatie' worden minimaal gebeurtenisgegevens verstrekt. Met behulp van verstrekte identificerende gegevens kan een consumer eventueel aanvullende gegevens gaan opvragen. + +Binnen de overheid komen al deze soorten notificaties voor. Bij een gegevensgerichte werkwijze wordt bijvoorbeeld vaak gebruik gemaakt van 'was-wordt gegevens', die de toestand van gegevensobjecten voor en na een plaatsgevonden gebeurtenis beschrijven, terwijl bij meer event georiënteerd werken vaak de gebeurtenis zelf wordt beschreven. De context bepaalt welke vorm van notificeren wanneer het geschiktst is. Daarbij spelen inhoudelijke aspecten een rol (bijvoorbeeld of privacygevoelige gegevens onderdeel van een notificatie mogen zijn) en praktische aspecten (bijvoorbeeld of afnemende applicaties in staat zijn om bepaalde soorten notificaties te verwerken). + +Notificaties kunnen verschillende vormen aannemen, zoals een pushmelding op een smartphone, een e-mail of sms-bericht, een melding op een beeldscherm binnen een applicatie, of elektronische berichten die via API-calls worden verstuurd. + +### Brongegevens en notificeren + +De afgelopen jaren is binnen de overheid veel energie gestoken in het gemakkelijker kunnen opvragen van brongegevens via moderne Application Programming Interfaces ([API's). In lijn met het principe 'Informeer bij de bron' wordt het daarmee beter mogelijk om gebruik te maken van gegevens in bronregistraties. Uitsluitend kunnen opvragen van brongegevens is voor veel processen echter niet genoeg om er optimaal gebruik van te maken. (Ook) notificeren is nodig om proactief te kunnen handelen of om tijdig actie te ondernemen als eerder opgevraagde brongegevens zijn gewijzigd. Voor optimaal gebruik van bronregistraties moeten bronhouders afnemers dus ook via notificaties informeren over relevante plaatsgevonden gebeurtenissen. Bijvoorbeeld als die hebben geleid tot wijziging van bepaalde brongegevens. Afnemers op hun beurt moeten zorgen dat door hen gebruikte applicaties ontvangen notificaties goed kunnen verwerken. + +### Standaardisatie + +Bij notificeren wordt allerlei soorten informatie tussen allerlei soorten partijen en applicaties uitgewisseld. Om te voorkomen dat organisaties te maken krijgen met veel, vaak onnodige, verschillen is standaardisatie op meerdere vlakken nodig. De [NL GOV Profile for CloudEvents](https://gitdocumentatie.logius.nl/publicatie/notificatieservices/CloudEvents-NL/) standaard beschrijft hoe plaatsgevonden gebeurtenissen door middel van een aantal standaard attributen, met een vast formaat en betekenis, zijn te beschrijven. Overheidsbreed gebruik van deze standaard vergemakkelijkt het maken, uitwisselen en verwerken van notificaties. + +Mede omdat notificaties vaak domeingrenzen overschrijden is ook semantische standaardisatie nodig. Het moet voor alle partijen duidelijk zijn wat de precieze betekenis van de gegevens binnen notificatie is. Een belangrijke eerste stap daarvoor is het zorgvuldig definiëren en documenteren van gebeurtenistypes. Gelet op de grote hoeveelheid betrokken partijen en mogelijke soorten notificaties is het wenselijk dat informatie over beschikbare notificaties op een gestandaardiseerde manier wordt gepubliceerd. Al dan niet via een of meer overheidsbreed toegankelijk catalogi. + +### Intern en extern notificeren + +Er zijn verschillende situaties waarin applicaties elkaar kunnen notificeren over bepaalde plaatsgevonden gebeurtenissen. Notificeren kan bijvoorbeeld plaatsvinden binnen 1 applicatie (bijvoorbeeld om geautomatiseerd de juiste acties in de juiste volgorde te laten uitvoeren), tussen applicaties binnen 1 organisatie (bijvoorbeeld om interne applicaties te informeren als in een Burgerzakenapplicatie wordt geregistreerd dat een inwoner is overleden) of tussen applicaties van verschillende organisaties (bijvoorbeeld als vanuit de RDW externe applicaties worden geïnformeerd dat een voertuig een nieuwe eigenaar heeft gekregen). Gemeenten hebben te maken met alle 3 soorten use cases. + +## Publish-subscribe patroon + +Het publish-subscribe patroon (pub/sub) is een veelgebruikt patroon binnen event-driven architecturen. Het patroon scheidt zenders (publishers) van events van ontvangers (subscribers) van events. Toepassing van dit patroon maakt het mogelijk om flexibele en schaalbare systemen te maken waarmee informatie over plaatsgevonden gebeurtenissen is uit te wisselen. + +Het patroon is een bekend voorbeeld van toepassing van eventoriëntatie. Vooral toegepast in situaties waarin meerdere applicatie graag op de hoogte willen worden gebracht ('genotificeerd') als er bepaalde gebeurtenissen hebben plaatsgevonden (zie [Notificeren introductie](https://www.gemmaonline.nl/wiki/Notificeren_introductie)). + +### Terminologie + +Binnen deze thema-architectuur gebruiken we de temen 'producer' en 'consumer' voor het aanduiden van de rol die applicaties spelen bij het uitwisselen van events. Vanwege de belangrijke rol die 'abonneren' speelt binnen het patroon spreekt het publish-subscribe patroon over de rollen: + +- **Publisher:** de rol verantwoordelijk voor het publiceren ('publish') van events, en +- **Subscriber:** de rol verantwoordelijk voor het abonneren ('subscribe') op het ontvangen van bepaalde soorten events. + +'Publisher' is te zien als 'producer' (waarbij vaak aanvullende eisen gelden voor publishers). 'Subscriber' is een 'consumer' die via een abonnement aangeeft welke events hij wil ontvangen. + +Net als bij andere vormen van event-uitwisseling wordt vaak gebruik gemaakt van een 'intermediairy': een tussenliggende applicatie die door producers gepubliceerde events verwerkt. In de praktijk wordt bij toepassing van het publish-subscribe protocol ook vaak een meer specifieke aanduiding gebruikt, zoals 'message broker' of 'event broker'. + +### Werking + +Subscribers geven via een abonnement ('subscription') aan over welke soorten plaatsgevonden gebeurtenissen zij events willen ontvangen. Publishers publiceren events naar een intermediair, die zorgt voor verstrekking van de juiste events aan geabonneerde consumers. Subscribers ontvangen zo de events waarin zij zijn geïnteresseerd. + +
+ +
Publish-subscribe patroon
+
+ +Toelichting: + +- Abonnementsgegevens worden veelal handmatig ingebracht. Het kan ook (deels) geautomatiseerd plaatsvinden. Daarvoor is nog geen standaard. Er wordt hiervoor gewerkt aan een [een internationale standaard.](https://github.com/cloudevents/spec/blob/main/subscriptions/spec.md) +- De rollen van publisher, intermediair en subscriber kunnen worden ingevuld door 1 of meerdere applicaties (en eigendom zijn van 1 of meer organisaties). +- Door gebruik te maken van een aparte applicatie in de rol van intermediair kunnen publishers en subscribers los van elkaar functioneren. Publishers hoeven dan bijvoorbeeld niet te weten welke soorten gepubliceerde events aan welke 'subscribers' events moeten worden verstrekt. +- De rol van intermediair wordt vaak vervuld door gespecialiseerde applicaties ('middleware') waarmee events veilig en betrouwbaar zijn uit te wisselen. +- Bij het uitwisselen van events wordt meestal asynchroon gecommuniceerd, zodat applicaties zo onafhankelijk mogelijk van elkaar kunnen werken. +- Bij het uitwisselen van events kan een keten aan betrokken applicaties ontstaan. Bijvoorbeeld als meerdere intermediairs met elkaar communiceren of als een applicatie in de rol van subscriber een ontvangen event in de rol van publisher of intermediair naar andere applicaties doorstuurt. Met name in cloudomgevingen wordt veel gebruik gemaakt van events die door verschillende soorten applicaties worden verwerkt. + +### Voorbeelden + +Het publish-subscribe patroon is toe te passen in uiteenlopende situaties, zoals: + +- Een nieuwssite publiceert een event met gegevens over een plaatsgevonden sportwedstrijd. De intermediair stuurt het event vervolgens als pushbericht naar de smartphones van gebruikers die zijn geabonneerd op events in de categorie 'sport'. +- Een overheidsportaal publiceert een event met gegevens over een aangevraagde vergunning. De intermediair verstrekt het event vervolgens aan een betaalsysteem, een vergunningenapplicatie en een klantnotificatiesysteem. +- Het Kadaster publiceert een event met informatie over een plaatsgevonden perceelsplitsing, zoals vastgelegd in de Basisregistratie Kadaster (BRK). De applicatie Digilevering verstrekt in de rol van intermediair het event aan alle op dit soort events geabonneerde applicaties. + +### Mogelijke voordelen + +Gebruik van het patroon kan veel voordelen opleveren: + +- **Losse koppeling:** Publishers en subscribers kunnen onafhankelijk van elkaar functioneren. +- **Schaalbaarheid:** Het aantal subscribers kan eenvoudig toenemen, zonder dat dit gevolgen heeft voor de publisher. +- **Asynchrone verwerking:** Events hoeven niet allemaal direct verwerkt te worden, waardoor systemen niet overbelast raken. +- **Realtime updates:** Gebruikers of systemen kunnen snel op de hoogte worden gebracht van plaatsgevonden gebeurtenissen. +- **Modulariteit:** Door de scheiding tussen eventproductie en eventconsumptie kunnen nieuwe functionaliteiten worden toegevoegd, zonder dat de bestaande infrastructuur moet worden aangepast. + +Het publish-subscribe patroon is heel geschikt voor gebruik binnen gedistribueerde omgevingen waarin registraties en applicaties over meerdere organisaties verspreid zijn. Omdat gemeenten met veel partijen samenwerken, daarmee intensief gegevens uitwisselen en belang hebben bij snelle informering over bepaalde gebeurtenissen, is het voor hen een patroon dat vaak bruikbaar is. + +### Mogelijke nadelen + +Net als bij andere patronen geldt ook voor het publish-subscribe patroon dat gebruik ervan ook een aantal nadelen kan kennen: + +- Verlies van berichten: events kunnen verloren gaan. Bijvoorbeeld als een verstrekking van een event aan een subscriber niet is gelukt. +- Onjuiste volgorde: afhankelijk van de implementatie kunnen berichten in een andere volgorde bij subscribers aankomen dan ze zijn verstuurd. Dit kan bij sommige toepassingen tot problemen leiden. +- Vertraging: events kunnen vertraagd worden verwerkt. Bijvoorbeeld als het gaat om grote volumes aan events of als een betrokken applicatie tijdelijk offline is. +- Complexiteit: het is moeilijker om fouten te traceren dan bij directe communicatie tussen publishers en subscribers. Debugging en monitoring is uitdagender. +- Abonnementsbeheer: het kan ingewikkeld zijn om in abonnementen vast te leggen aan welke subscribers welke events moeten worden verstrekt. + +De genoemde nadelen zijn via de juiste maatregelen op te heffen. De inzet van gespecialiseerde applicaties voor de rol van intermediair is een voorbeeld daarvan. Via bijvoorbeeld queuing en (tijdelijke of permanente) opslag van events kunnen optredende fouten of verstoringen dan goed worden afgehandeld. Naast lokale voorzieningen om nadelen op te heffend wordt in toenemende mate gebruik gemaakt van door cloudproviders aangeboden voorzieningen. + +### Opmerkingen + +In de praktijk wordt niet altijd hetzelfde bedoeld met 'het publish-subscribe patroon': + +- Soms wordt asynchrone verwerking gezien als een voorwaarde om te kunnen spreken over gebruik van het publish-subscribe patroon. Synchrone communicatie kan echter ook een rol spelen. Bijvoorbeeld als een publisher snelle terugkoppeling nodig heeft en daarvoor wacht op feedback van de intermediair of als een intermediair na verstrekking van een event bereid is te wachten op feedback van een consumer. +- Bij gebruik van het patroon is gebruik te maken van zowel push- als pull-mechanismen en een combinatie van beide: + - **Push:** het meest toegepaste mechanisme, waarbij nieuwe events actief richting subscribers worden gestuurd. Bijvoorbeeld via het webhook-patroon, waar afnemers bij abonneren opgeven welke service kan worden aangeroepen om events af te leveren (zie ook de [handreiking](https://gitdocumentatie.logius.nl/publicatie/notificatieservices/guidelines/#guideline-for-the-use-of-the-webhook-pattern-for-cloudevents) voor gestandaardiseerd gebruik van webhooks). + - **Pull:** bijvoorbeeld toegepast als subscribers geen push-mechanisme kunnen ondersteunen of als het voor consumers niet nodig is om events snel te ontvangen. Een publisher kan dan bijvoorbeeld events vastleggen die subscribers later, op een zelf te kiezen moment, via een service ophalen. + - **Push en pull:** een voorbeeld hiervan is de situatie dat een subscriber het initiatief neemt om een verbinding op te zetten met een publisher ('pull'), waarna de publisher de verbinding gebruikt om beschikbaar komende events direct te verstrekken ('push'). Protocollen die dit mechanisme ondersteunen zijn bijvoorbeeld het [Advanced Message Queuing Protocol](https://en.wikipedia.org/wiki/Advanced_Message_Queuing_Protocol) (AMQP) en [Server-sent events](https://en.wikipedia.org/wiki/Server-sent_events). +- Uitwisseling van events via een publish-subscribe patroon kan plaatsvinden met gebruik van verschillende gegevensformaten, transportprotocollen en technologiecomponenten. Qua protocol kan bijvoorbeeld gebruik worden gemaakt van een breed toepasbaar protocol zoals HTTP of van specifiek voor event-verwerking ontwikkelde protocollen zoals AMQP of MQTT. Door gebruik te maken van een standaard zoals CloudEvents,, en het daarvan afgeleide NL GOV for Cloudevents profiel, wordt het mogelijk om met events te werken binnen een divers technologisch landschap. + +## Randvoorwaarden voor notificeren + +Voor een bredere adoptie binnen de Nederlandse overheid van notificeren, en meer algemeen eventoriëntatie, moet aan verschillende soorten randvoorwaarden worden voldaan: + +- **Mindset**: er is een verschuiving nodig van een gegevens- naar een meer gebeurtenisgerichte benadering. Veel organisaties baseren hun processen nog op statische gegevens, terwijl een notificatie juist reageert op gebeurtenissen. Zowel aanbieders als afnemers moeten nut en noodzaak ervan gaan inzien. Waar de noodzaak al wordt ingezien is dit vaak meer vanuit technische- dan vanuit business-motieven. +- **Begrippen**: een eenduidig begrippenkader is nodig om te zorgen dat alle betrokkenen dezelfde taal spreken en elkaar begrijpen. Dit document sluit aan bij de terminologie die wordt gebruikt bij landelijke ontwikkelingen zoals de GDI-domeinarchitectuur Gegevensuitwisseling en de [NL GOV for CloudEvents standaard](https://www.logius.nl/domeinen/gegevensuitwisseling/nl-gov-profile-cloudevents). +- **Juridisch**: juridische vraagstukken, zoals rondom de privacywetgeving, spelen een belangrijke rol bij het verstrekken van notificaties. Wanneer er persoonsgegevens bij betrokken zijn moet toetsbaar zijn of voldoende grondslag bestaat om een verzoek tot ontvangen van notificaties in te willigen. Het redeneren vanuit gebeurtenissen sluit goed aan bij de notitie van de 'verwerkingsactiviteit', zoals beschreven in de AVG. Hier liggen dan ook kansen om uitdagingen op dit gebied beter te organiseren. +- **Techniek**: bronnen moeten niet meer alleen informatie verstrekken over wat er is gewijzigd, maar ook waarom dit is gebeurd. Veel bronnen zijn hier nu niet toe in staat en dus zijn technische aanpassingen nodig. Voor afnemers geldt dat zij applicaties geschikt moeten (laten) maken om goed om te kunnen gaan met verstrekte notificaties. +- **Standaardisatie**: vanwege de diversiteit aan betrokken partijen, gegevens en technische middelen is op verschillende vlakken standaardisatie nodig. Naarmate het gebruik van elders vastgelegde brongegevens toeneemt, neemt de noodzaak hiervan toe omdat afnemers uit steeds meer bronnen notificaties ontvangen. +- **Betrouwbaarheid**: Er is een gebrek aan vertrouwen in de gegevenskwaliteit van sommige bronregistraties. Reden waarom afnemers brongegevens lokaal opslaan en werken met bestandsvergelijkingen in plaats van notificaties. Waar nodig moet de kwaliteit van bronregistraties worden verbeterd en er op vertrouwd worden dat brongegevens betrouwbaar zijn. +- **Inzicht**: Afnemers moeten kunnen opvragen welke soorten notificaties er binnen de overheid worden aangeboden. Met deze informatie moet inzichtelijk worden wat de voorwaarden voor gebruik zijn en moeten specificaties voor gebruik (door mensen en machines) zijn op te vragen. +- **Kosten**: Vanuit de 1-overheidsgedachte is het wenselijk dat alle overheidsorganisaties die er belang bij hebben om te weten dat bepaalde gebeurtenissen hebben plaatsgevonden, dit tijdig weten. De grootste meerwaarde van notificaties ligt vaak buiten de organisaties die events publiceren en daarvoor kosten moeten maken. Huidige kostenstructuren werken nog te vaak belemmerend voor het overheidsbreed optimaliseren van notificeren. +- **Samenwerking**: Notificaties zijn pas echt bruikbaar als ze aansluiten bij de behoeften van afnemers. Aanbieders moeten daarom vroegtijdig overleggen met (potentiële) afnemers over het soort te leveren notificaties en de inhoud daarvan. Aanbieders zijn vanuit hun taakstelling nu nog vaak, teveel gericht op vastlegging en beheer van brongegevens. Definiëren van gebeurtenistypes geeft een handreiking voor het benoemen van te notificeren gebeurtenissen. + +Veel van deze randvoorwaarden zijn niet uniek voor notificeren, maar gaan over het gebruik van gegevens in het algemeen. Programma's als de [Interbestuurlijke Datastrategie](https://www.digitaleoverheid.nl/interbestuurlijke-datastrategie/), met als onderdeel het project [Federatief Datastelsel](https://realisatieibds.nl/page/view/564cc96c-115e-4e81-b5e6-01c99b1814ec/de-ontwikkeling-van-het-federatief-datastelsel), hebben als doel om hier als overheid beter in te worden. Gebruik van event-driven architectuur kan een belangrijke bijdrage leveren aan realisatie van doelen zoals 'het faciliteren van zoeken, delen en in samenhang toepassen van hoogwaardige data uit verschillende databronnen voor meervoudig gebruik'. + +Bovenstaande opsomming richt zich vooral op de overheidsbrede toepassing van notificeren. Maar individuele organisaties kunnen ook zelf stappen zetten door te bezien hoe gebruik van events de eigen informatievoorziening kan verbeteren. Denk aan het meervoudig gebruik van bronregistraties in plaats van gegevens vaker op slaan, het vervangen van periodieke bestandsuitwisselingen door notificaties of het binnen applicaties werken met notificaties in plaats van complexe voorgedefinieerde workflows. + +## Informatiearme en informatierijke notificaties + +Om afnemers op de hoogte te brengen dat er een bepaalde gebeurtenis heeft plaatsgevonden kan gebruik worden gemaakt van zogenaamde 'informatiearme' of 'informatierijke' notificaties. De termen verwijzen naar de hoeveelheid informatie die is opgenomen in een notificatiebericht. + +### Informatiearme notificaties + +Een informatiearme notificatie bevat de minimale set aan gegevens over een plaatsgevonden gebeurtenis die consumers nodig hebben. Een informatiearme notificatie bevat identificerende gegevens die een afnemer kan gebruiken om om aanvullende detailgegevens op te halen. Een voorbeeld hiervan is een notificatie waarin naast een gebeurtenisbron en gebeurtenistype alleen een gebeurtenis-identificatie is opgenomen. Bijvoorbeeld "[Basisregistratie Kadaster", "KadastraleGroottePerceelGewijzigd", "KPC024453"]. Na ontvangst van zo'n notificatie kan een consumer beslissen om een service bij het Kadaster aan te roepen waarmee aanvullende detailinformatie over de plaatsgevonden wijziging is op te vragen. + +### Informatierijke notificaties + +Een informatierijke notificatie bevat de volledige informatie over een plaatsgevonden gebeurtenis. Een afnemer hoeft dan na ontvangst geen aanvullende gegevens meer op te vragen. Ten opzichte van het informatiearme voorbeeld zijn binnen de notificatie dan ook beschrijvende gebeurtenisgegevens opgenomen. Bijvoorbeeld "KadastraleGrootteOud=3000, KadastraleGrootteNieuw=3500". + +### Informatiearm of informatierijk? + +Een voordeel van informatiearm notificeren is dat er niet meer gegevens worden uitgewisseld dan minimaal nodig is. Iets dat nodig kan zijn om privacy en beveiliging te borgen of om bij een beperkte bandbreedte overbelasting te voorkomen. Een voordeel van informatierijk notificeren voor afnemers is dat ze geen aanvullende gegevens meer op hoeven te vragen, maar direct kunnen overgaan tot verwerking. Het ontlast ook de aanbieder die geen aparte service voor opvraging van detailgegevens hoeft aan te bieden. + +Beide soorten notificaties hebben bestaansrecht. Welke type notificatie in een bepaalde situatie het meest geschikt is wordt bepaald door de context. Daarbij kunnen factoren een rol spelen zoals wetgeving, mogelijkheden, gemak en kosten. + +### Notificeren van gewijzigde brongegevens + +In lijn met het principe 'Data bij de bron' is de wens om brongegevens niet onnodig lokaal op te slaan, maar gebruik te maken van verwijzingen. Voor beide situaties geldt dat het vaak nodig is om notificaties te ontvangen als bepaalde brongegevens zijn gewijzigd. Wanneer naar elders vastgelegde brongegevens wordt verwezen kan informatiearm vaak volstaan. Zijn gegevens lokaal vastgelegd dan kan het efficiënter zijn om gewijzigde gegevens direct te ontvangen via informatierijke notificaties. + +## ZGW Notificaties API-standaard + +De [ZGW Notificaties API](https://vng-realisatie.github.io/gemma-zaken/standaard/notificaties/) is een API-standaard die behoort tot de [API-standaarden voor zaakgericht werken](https://vng-realisatie.github.io/gemma-zaken/standaard/). De standaard is ontwikkeld om bij zaakgericht werken gestandaardiseerd notificaties te kunnen gebruiken. Bij zaakgericht werken worden notificaties met name gepubliceerd door de [zaakregistratiecomponent](https://www.gemmaonline.nl/wiki/GEMMA/id-a97b6545-d5a7-485d-9b13-3ce22db5b9cf) en de [documentregistratiecomponent](https://www.gemmaonline.nl/wiki/GEMMA/id-0e99ec6c-283a-4ec9-8efa-e11468e6b878). Notificaties kunnen worden verstrekt aan alle applicaties die zich hebben geabonneerd op een bepaald soort plaatsgevonden gebeurtenissen waarover wordt genotificeerd. + +Op langere termijn is het de bedoeling om de standaard door te ontwikkelen tot een breed toepasbare API voor notificeren in het algemeen. Mede hiervoor heeft VNG Realisatie, in opdracht van het Ministerie van Binnenlandse Zaken, in 2021 het project 'Notificatieservices' uitgevoerd. Binnen het project is de concept standaard voor overheidsbreed notificeren ontwikkeld: de NL GOV Standaard for CloudEvents. Deze is onder andere beproefd tijdens een Hackathon waar gemeenten en leveranciers aan deelnamen. Een van de uitkomsten was dat de ZGW Notificaties API standaard relatief eenvoudig was [aan te passen](https://github.com/VNG-Realisatie/notificatieservices/tree/main/docs/api-specification) om te voldoen aan de beoogde overheidsbrede notificatie-standaard. + +Gelet op het feit dat gemeenten groot belang hebben bij overheidsbreed standaardiseren van notificeren, draagt de VNG nu actief bij aan het doorontwikkelen van de [NL GOV for CloudEvents standaard](https://www.gemmaonline.nl/wiki/NL_GOV_Profile_for_CloudEvents_introductie). De standaard is in behandeling bij het Forum Standaardisatie om opgenomen te worden in de verzameling overheidsbrede [pas-toe-leg-uit standaarden](https://www.forumstandaardisatie.nl/open-standaarden/verplicht) en wordt al op beperkte schaal gebruikt binnen de overheid en door leveranciers op de gemeentemarkt. diff --git a/API-strategie-best-practices/event-driven-architecture/js/config.js b/API-strategie-best-practices/event-driven-architecture/js/config.js new file mode 100644 index 00000000..7b672478 --- /dev/null +++ b/API-strategie-best-practices/event-driven-architecture/js/config.js @@ -0,0 +1,92 @@ +let respecConfig = { + useLogo: true, + useLabel: true, + // title is verplicht! Neem hier de titel van het document op ---------------------- + title: "Event Driven Architecture (EDA) - Best Practice", + //-- specStatus is verplicht! (activeer 1 van de volgende) -------------------------- + specStatus: "wv", // Werkversie + //specStatus: "cv", // Consultatieversie + //specStatus: "vv", // Versie ter vaststelling + //specStatus: "def", // Vastgestelde versie + //specStatus: "basis", // Basis Document + //-- specType is verplicht bij alle andere dan BASIS --------------------------------- + //specType: "NO", // Norm + //specType: "ST", // Standaard + //specType: "IM", // Informatie Model + //specType: "PR", // Praktijkrichtlijn + specType: "HR", // HandReiking + //specType: "WA", // Werkafspraak + //specType: "BD", // Beheer Documentatie + //specType: "AL", // Algemeen document + //specType: "BP", // Best Practice + //-- pubDomain is verplicht! (komt in de URL) ------------------------------------- + pubDomain: "api", + //-- license: voor de geldende gebruiksvoorwaarden. Default is cc-by. + //licence: "cc-by-nd", // bronvermelding, geen afgeleide werken (default) + //licence: "cc0", // Public Domain Dedication + licence: "cc-by", // Attribution, met bronvermelding + //-- shortName is verplicht! (komt in de URL: kies logische afkorting)-------------- + shortName: "API-Strategie-EDA", + edDraftURI: + "https://geonovum.github.io/KP-APIs/API-strategie-best-practices/event-driven-architecture/", + //edDraftURI = De URI van de draft version. Deze wordt automatisch afgeleid van de github URI; maar kan hier overschreven worden. + //edDraftURI: ["https://geonovum.github.io", "/", "shortName"], + + //-- publishDate is verplicht ------------------------------------------------------- + //-- NB: in de werkversie uitzetten, want dan pakt Respec de pushdate --------------- + //publishDate: "2023-12-21", + //eventueel is het mogelijk een versienummer mee te geven, maar bij Geonovum werken we gewoonlijk alleen met datum als onderdeel van de permanente URI. + publishVersion: "0.0.1", + //previousVersion: "0.0.1", + //-- Voor dit blok geldt: alleen als er eerdere versies zijn en altijd beiden aan/uit! + //previousPublishDate: "2023-12-21", + //previousMaturity: "vv", + //-- de namen van de Editor(s) / Redacteur(en)--------------------------------------- + //-- vul in: per Editor: name:, company:, companyURL: ------------------------------- + editors: [ + { + name: "Kennisplatform API's", + company: "Kennisplatform API's", + companyURL: "https://github.com/Geonovum/KP-APIs", + }, + { + name: "Martin van der Plas", + company: "Geonovum", + companyURL: "https://github.com/Geonovum/KP-APIs", + }, + ], + authors: [ + { + name: "Kennisplatform API's", + company: "Kennisplatform API's", + companyURL: "https://github.com/Geonovum/KP-APIs", + }, + { + name: "VNG Realisatie", + company: "Vereniging van Nederlandse Gemeenten (VNG)", + companyURL: "https://vng.nl", + }, + ], + //neem hier de URL van de github repository op waar het respec document in staat + github: "https://github.com/Geonovum/KP-APIs", + // Controls if linked "§" section markers are added to a document + addSectionLinks: true, + + localBiblio: { + GEMMA: { + href: "https://www.gemmaonline.nl/", + title: + "'GEMMA' staat voor de 'GEMeentelijke Model Architectuur': de referentiearchitectuur voor Nederlandse gemeenten.", + authors: ["-"], + date: " 2016-01-01", + }, + }, + + // Create PDF and link to file in header (optional): + //alternateFormats: [ + // { + // label: "pdf", + // uri: "template.pdf", + // }, + // ], +}; diff --git a/API-strategie-best-practices/event-driven-architecture/js/organisation-config.js b/API-strategie-best-practices/event-driven-architecture/js/organisation-config.js new file mode 100644 index 00000000..04c791d7 --- /dev/null +++ b/API-strategie-best-practices/event-driven-architecture/js/organisation-config.js @@ -0,0 +1,156 @@ +// Dit bestand is gepubliceerd als https://tools.geostandaarden.nl/respec/config/geonovum-config.js, voor hergebruik in Geonovum ReSpec documenten. +var organisationConfig = { + nl_organisationName: "Geonovum", + // werkt nog niet + // nl_organisationStylesURL: "https://tools.geostandaarden.nl/respec/gn-algemeen/style/", + // bv styles url voor ander GN publicatiedomein met eigen stijlen zoals DSO of BRO: + // nl_organisationStylesURL: "https://tools.geostandaarden.nl/respec/dso/style/", + // nl_organisationStylesURL: "https://tools.geostandaarden.nl/respec/bro/style/", + nl_organisationPublishURL: "https://docs.geostandaarden.nl/", + logos: [ + { + src: "https://tools.geostandaarden.nl/respec/style/logos/Geonovum.svg", + alt: "Geonovum", + id: "Geonovum", + height: 67, + width: 132, + url: "https://www.geonovum.nl/geo-standaarden", + }, + ], + + postProcess: [window.respecMermaid.createFigures], + + latestVersion: [ + "nl_organisationPublishURL", + "pubDomain", + "/", + "shortName", + "/", + ], + thisVersion: [ + "nl_organisationPublishURL", + "pubDomain", + "/", + "specStatus", + "-", + "specType", + "-", + "shortName", + "-", + "publishDate", + ], + prevVersion: [ + "nl_organisationPublishURL", + "pubDomain", + "/", + "previousMaturity", + "-", + "specType", + "-", + "shortName", + "-", + "previousPublishDate", + ], + useLogo: true, + useLabel: true, + + license: "cc-by", + addSectionLinks: true, + + localizationStrings: { + en: { + wv: "Editor's draft", + cv: "Candidate recommendation", + vv: "Proposed recommendation", + def: "Recommendation", + basis: "Document", + //eo: "Outdated version", + //tg: "Rescinded version", + no: "Norm", + st: "Standard", + im: "Information model", + pr: "Practical guideline", + hr: "Guide", + wa: "Work process agreement", + al: "General", + bd: "Governance documentation", + bp: "Best practice", + }, + nl: { + wv: "Werkversie", + cv: "Consultatieversie", + vv: "Versie ter vaststelling", + def: "Vastgestelde versie", + basis: "Document", + //eo: "Verouderde versie", + //tg: "Teruggetrokken versie", + no: "Norm", + st: "Standaard", + im: "Informatiemodel", + pr: "Praktijkrichtlijn", + hr: "Handreiking", + wa: "Werkafspraak", + al: "Algemeen", + bd: "Beheerdocumentatie", + bp: "Best practice", + }, + }, + + sotdText: { + nl: { + sotd: "Status van dit document", + def: `Dit is de definitieve versie van dit document. Wijzigingen naar aanleiding van consultaties zijn doorgevoerd.`, + wv: `Dit is een werkversie die op elk moment kan worden gewijzigd, verwijderd of vervangen door andere documenten. Het is geen stabiel document.`, + cv: `Dit is een consultatieversie. Commentaar over dit document kan gestuurd worden naar `, + vv: `Dit is de definitieve conceptversie van dit document. Wijzigingen naar aanleiding van consultaties zijn doorgevoerd.`, + basis: "Dit is een document zonder officiële status.", + }, + en: { + sotd: "Status of this document", + def: `This is the definitive version of this document. Edits resulting from consultations have been applied.`, + wv: `This is a working draft that can be changed, removed or replaced by other documents at any time. It is not a stable document.`, + cv: `This is a stable draft, published for public comment. Comments regarding this document may be sent to `, + vv: `This is the final draft of this document. Edits resulting from consultations have been applied.`, + basis: "This document has no official standing.", + }, + }, + + labelColor: { + def: "#045D9F", + wv: "#FF0000", + cv: "#045D9F", + vv: "#045D9F", + basis: "#80CC28", + }, + + licenses: { + cc0: { + name: "Creative Commons 0 Public Domain Dedication", + short: "CC0", + url: "https://creativecommons.org/publicdomain/zero/1.0/", + image: + "https://tools.geostandaarden.nl/respec/style/logos/CC-Licentie.svg", + }, + "cc-by": { + name: "Creative Commons Attribution 4.0 International Public License", + short: "CC-BY", + url: "https://creativecommons.org/licenses/by/4.0/legalcode", + image: "https://tools.geostandaarden.nl/respec/style/logos/cc-by.svg", + }, + "cc-by-nd": { + name: "Creative Commons Naamsvermelding-GeenAfgeleideWerken 4.0 Internationaal", + short: "CC-BY-ND", + url: "https://creativecommons.org/licenses/by-nd/4.0/legalcode.nl", + image: "https://tools.geostandaarden.nl/respec/style/logos/cc-by-nd.svg", + }, + }, + + localBiblio: { + SemVer: { + href: "https://semver.org", + title: "Semantic Versioning 2.0.0", + authors: ["T. Preston-Werner"], + date: "June 2013", + }, + }, +}; diff --git a/inleiding.md b/inleiding.md index a83392b2..248f3e2e 100644 --- a/inleiding.md +++ b/inleiding.md @@ -22,22 +22,23 @@ De API strategie bestaat uit een een inleidend document, verschillende normatiev De verschillende onderdelen van de NL API Strategie bevat de volgende documenten: -| Onderdeel | Documentnaam &
Verwijzing naar de gepubliceerde versie | Status | Versie | -| -------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ----------------------- | -| Algemeen | [Inleiding NL API Strategie](https://docs.geostandaarden.nl/api/API-Strategie/) | Vastgesteld
(door Kennisplatform) | 08-03-2024 | -| Algemeen | [Architectuur NL API Strategie](https://docs.geostandaarden.nl/api/API-Strategie-architectuur/) | Vastgesteld
(door Kennisplatform) | 08-03-2024 | -| Algemeen | [Gebruikerswensen NL API Strategie](https://docs.geostandaarden.nl/api/API-Strategie-gebruikerswensen/) | Vastgesteld
(door Kennisplatform) | 08-03-2024 | -| Normatieve standaard | [API Design Rules (ADR)](https://gitdocumentatie.logius.nl/publicatie/api/adr/) | Verplicht
(pas toe leg uit) | 09-07-2020
v1.0.0 | -| Normatieve standaard | [API Design Rules (ADR)](https://gitdocumentatie.logius.nl/publicatie/api/adr/) | Verplicht \*
(door MIDO) | 08-03-2024
v2.0.0 | -| Verplichte standaard | [Open API Specification (OAS)](https://forumstandaardisatie.nl/open-standaarden/openapi-specification) | Verplicht
(pas toe leg uit) | 25-05-2018
v3.0.0 | -| Normatieve standaard | [NL GOV OAuth profiel](https://gitdocumentatie.logius.nl/publicatie/api/oauth/) | Verplicht
(pas toe leg uit) | 09-07-2020
v1.0.0 | -| Verplichte standaard | [NL GOV OpenID Connect profile](https://logius.gitlab.io/oidc/) | Verplicht
(pas toe leg uit) | 18-02-2021
v1.0.0 | -| Verplichte standaard | [Digikoppeling REST API koppelvlak specificatie](https://gitdocumentatie.logius.nl/publicatie/dk/restapi/) | Verplicht
(pas toe leg uit) | 14-11-2022
v1.1.1 | -| Normatieve standaard | [API Geospatial module](https://docs.geostandaarden.nl/api/API-Strategie-mod-geo/) | Verplicht \*
(door MIDO) | 08-03-2024 | -| Normatieve standaard | [API Transport Security module](https://docs.geostandaarden.nl/api/API-Strategie-mod-transport-security/) | Verplicht \*
(door MIDO) | 08-03-2024 | -| Aanvullende module | [API Access control module](https://docs.geostandaarden.nl/api/API-Strategie-mod-access-control/) | Vastgesteld
(door Kennisplatform) | 08-03-2024 | -| Aanvullende module | [API Naming conventions module](https://docs.geostandaarden.nl/api/API-Strategie-mod-naming-conventions/) | Vastgesteld
(door Kennisplatform) | 08-03-2024 | -| Aanvullende module | [API Hypermedia module](https://docs.geostandaarden.nl/api/API-Strategie-mod-hypermedia/) | Stabiel
(Werkgroep Kennisplatform) | 12-07-2023 | -| Aanvullende module | [API Batching module](https://geonovum.github.io/KP-APIs/API-strategie-modules/batching/) | Concept
(Werkgroep Kennisplatform) | | +| Onderdeel | Documentnaam &
Verwijzing naar de gepubliceerde versie | Status | Versie | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ----------------------- | +| Algemeen | [Inleiding NL API Strategie](https://docs.geostandaarden.nl/api/API-Strategie/) | Vastgesteld
(door Kennisplatform) | 08-03-2024 | +| Algemeen | [Architectuur NL API Strategie](https://docs.geostandaarden.nl/api/API-Strategie-architectuur/) | Vastgesteld
(door Kennisplatform) | 08-03-2024 | +| Algemeen | [Gebruikerswensen NL API Strategie](https://docs.geostandaarden.nl/api/API-Strategie-gebruikerswensen/) | Vastgesteld
(door Kennisplatform) | 08-03-2024 | +| Normatieve standaard | [API Design Rules (ADR)](https://gitdocumentatie.logius.nl/publicatie/api/adr/) | Verplicht
(pas toe leg uit) | 09-07-2020
v1.0.0 | +| Normatieve standaard | [API Design Rules (ADR)](https://gitdocumentatie.logius.nl/publicatie/api/adr/) | Verplicht \*
(door MIDO) | 08-03-2024
v2.0.0 | +| Verplichte standaard | [Open API Specification (OAS)](https://forumstandaardisatie.nl/open-standaarden/openapi-specification) | Verplicht
(pas toe leg uit) | 25-05-2018
v3.0.0 | +| Normatieve standaard | [NL GOV OAuth profiel](https://gitdocumentatie.logius.nl/publicatie/api/oauth/) | Verplicht
(pas toe leg uit) | 09-07-2020
v1.0.0 | +| Verplichte standaard | [NL GOV OpenID Connect profile](https://logius.gitlab.io/oidc/) | Verplicht
(pas toe leg uit) | 18-02-2021
v1.0.0 | +| Verplichte standaard | [Digikoppeling REST API koppelvlak specificatie](https://gitdocumentatie.logius.nl/publicatie/dk/restapi/) | Verplicht
(pas toe leg uit) | 14-11-2022
v1.1.1 | +| Normatieve standaard | [API Geospatial module](https://docs.geostandaarden.nl/api/API-Strategie-mod-geo/) | Verplicht \*
(door MIDO) | 08-03-2024 | +| Normatieve standaard | [API Transport Security module](https://docs.geostandaarden.nl/api/API-Strategie-mod-transport-security/) | Verplicht \*
(door MIDO) | 08-03-2024 | +| Aanvullende module | [API Access control module](https://docs.geostandaarden.nl/api/API-Strategie-mod-access-control/) | Vastgesteld
(door Kennisplatform) | 08-03-2024 | +| Aanvullende module | [API Naming conventions module](https://docs.geostandaarden.nl/api/API-Strategie-mod-naming-conventions/) | Vastgesteld
(door Kennisplatform) | 08-03-2024 | +| Aanvullende module | [API Hypermedia module](https://docs.geostandaarden.nl/api/API-Strategie-mod-hypermedia/) | Stabiel
(Werkgroep Kennisplatform) | 12-07-2023 | +| Aanvullende module | [API Batching module](https://geonovum.github.io/KP-APIs/API-strategie-modules/batching/) | Concept
(Werkgroep Kennisplatform) | | +| Best Practice | [Event Driven Architecture (EDA)](https://geonovum.github.io/KP-APIs/API-strategie-best-practices/event-driven-architecture/) | Concept
(Werkgroep Kennisplatform) | | - Deze modules zijn normatief binnen de GDI, vaststellingsproces pas toe of leg uit lijst is nog in procedure diff --git a/media/API infographic.drawio b/media/API infographic.drawio index 07c3f407..915ee7ce 100644 --- a/media/API infographic.drawio +++ b/media/API infographic.drawio @@ -1,4 +1,399 @@ - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -499,4 +894,121 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/media/API_infographic.svg b/media/API_infographic.svg index 28717609..0c467659 100644 --- a/media/API_infographic.svg +++ b/media/API_infographic.svg @@ -1,4 +1,4 @@ -
Legenda
Legenda
Verplichte
'Pas toe of leg uit'
-lijst standaarden
Verplichte...
Algemene documenten
Inleiding
NL API Strategie
Inleiding...
Gebruikerswensen
NL API Strategie
Gebruikerswensen...
Architectuur
NL API Strategie
Architectuur...
Normatieve documenten
API Design Rules (ADR)
API Design Rules (ADR)
Open API Specification (OAS)
Open API Specification (OAS)
NL GOV OAuth profiel
NL GOV OAuth profiel
Digikoppeling REST API koppelvlak specificatie
Digikoppeling REST API koppelvla...
NL GOV OIDC profiel
NL GOV OIDC profiel
Geospatial module
Geospatial module
Signing module
Signing module
Encryption module
Encryption module
NL API Strategie
NL API Strategie
Modulen documenten
Notificeren (Cloudevents)
Notificeren (Cloudevents)
Versioning module
Versioning module
API Access module
API Access module
Naming conventions module
Naming conventions module
JSON module
JSON module
Filtering & Sorting module
Filtering & Sorting module
Search & Customization module
Search & Customization module
Temporal module
Temporal module
Hypermedia module
Hypermedia module
Pagination module
Pagination module
Caching module
Caching module
Rate limiting module
Rate limiting module
Error handling module
Error handling module
Delegation module
Delegation module
API Monitoring module
API Monitoring module
Discovery module
Discovery module
Logging module
Logging module
Batching module
Batching module
Vastgestelde algemene documenten
Vastgestelde algemen...
Concept modules
Concept modules
Stabiele modules
Stabiele modules
Laatst bijgewerkt:

dd. 20-05-2025
Versie 1.3.0
Laatst bijgewerkt:...
Infographic
NL API Strategie
Infographic...
Nog te ontwikkelen modules
Nog te ontwikkelen m...
Developer Overheid
Developer Overheid
Text is not SVG - cannot display
+
Legenda
Verplichte
'Pas toe of leg uit'
-lijst standaarden
Algemene documenten
Inleiding
NL API Strategie
Gebruikerswensen
NL API Strategie
Architectuur
NL API Strategie
Normatieve documenten
API Design Rules (ADR)
Open API Specification (OAS)
NL GOV OAuth profiel
Digikoppeling REST API koppelvlak specificatie
NL GOV OIDC profiel
Geospatial module
Signing module
Encryption module
NL API Strategie
Modulen documenten
Notificeren (Cloudevents)
Versioning module
API Access module
Naming conventions module
Search & Customization module
Hypermedia module
Event Driven Architecture (EDA) - Best Practices
Logging module
Batching module
Error handling module
Filtering & Sorting module
Rate limiting module
Caching module
JSON module
Temporal module
Pagination module
API Monitoring module
Discovery module
Delegation & Consent module
Vastgestelde algemene documenten
Concept modules
Stabiele modules
Laatst bijgewerkt:

dd. 15-09-2025
Versie 1.4.0
Infographic
NL API Strategie
Nog te ontwikkelen modules
Developer Overheid
\ No newline at end of file diff --git a/media/Event-driven_architectuur_1.png b/media/Event-driven_architectuur_1.png new file mode 100644 index 00000000..b4db24cb Binary files /dev/null and b/media/Event-driven_architectuur_1.png differ diff --git a/media/Publish-subscribe_patroon.png b/media/Publish-subscribe_patroon.png new file mode 100644 index 00000000..c4582bc0 Binary files /dev/null and b/media/Publish-subscribe_patroon.png differ