Handreiking NL GOV profile for CloudEvents

Algemeen

Beheerder: Logius

Status bij Forum Standaardisatie: pas toe, leg uit

Waarde van de standaard

NL GOV profile for CloudEvents is een set Nederlandse afspraken over het gebruik van de internationale standaard CloudEvents. Het beschrijft hoe een plaatsgevonden gebeurtenis beschreven en uitgewisseld kan worden.

Belangrijke voordelen van de CloudEvents standaard en het daarvan afgeleide Nederlandse profiel zijn:

Ondersteunen van notificeren, zodat partijen snel kunnen reageren op gebeurtenissen en zodat systemen beter kunnen worden ontkoppeld.
Standaardiseren van de inhoud en structuur van notificaties, zodat partijen en systemen deze eenvoudiger en met minder fouten kunnen begrijpen en verwerken;
Vertaling naar verschillende transportprotocollen, zodat contextueel het beste protocol kan worden gekozen;
Ondersteunen van de integratie van notificaties van heterogene bronnen, zodat deze via één gegevensdienst kunnen worden aangeboden aan afnemers;
Expliciete ondersteuning voor versionering van gebeurtenistypes en bijbehorende gegevensmodellen, zodat deze met beperkte impact kunnen wijzigen.
De mogelijkheid tot het definiëren van extensies, zodat de standaard contextueel kan worden uitgebreid.

De CloudEvents standaard en het daarvan afgeleide profiel biedt waarde aan de volgende specifieke doelgroepen:

Doelgroep	Waarde
Management	Verhogen van de robuustheid, flexibiliteit en schaalbaarheid van systemen door ontkoppeling op basis van gebeurtenissen. Verlagen van de afhankelijkheid van leveranciers en hun oplossingen voor notificeren, doordat deze eenvoudiger kunnen vervangen door andere oplossingen die de standaard ondersteunen.
Ontwikkelaars	Sneller event-gebaseerde applicaties kunnen ontwikkelen en integreren, doordat dit op een meer gestandaardiseerde wijze kan en doordat er SDK’s beschikbaar zijn. Wijzigingen in gebeurtenistypes en gegevensmodellen eenvoudig kunnen doorvoeren, doordat versionering wordt ondersteund.
Technisch beheerders	Verlagen beheerlast door het op gestandaardiseerde wijze kunnen routeren, loggen en monitoren van notificaties.

Werking van de standaard

De CloudEvents standaard beschrijft vooral een aantal standaard metagegevens die onderdeel zouden moeten uitmaken van notificaties. Het Nederlandse profiel beschrijft aanvullende richtlijnen, zodat deze metagegevens ook een gestandaardiseerde soort inhoud hebben.

De verplichte metagegevens voor notificaties zijn:

id: een unieke identificatie van de notificatie;
source: een identificatie van de bron (organisatie, systeem) van de gebeurtenis;
specversion: de versie van de CloudEvents specificatie die is gebruikt;
type: een identificatie van het gebeurtenistype;

De belangrijkste optionele metagegevens voor notificaties zijn:

datacontenttype: het formaat van de content in de notificatie;
dataschema: het gegevensmodel van de gegevens in de notificatie;
subject: een identificatie van het ding waar de gebeurtenis betrekking op heeft;
time: het tijdstip waarop de notificatie is vastgelegd.

De standaard is platform-, protocol- en formaatonafhankelijk. Het bevat wel mappings op een aantal transportprotocollen. Tenslotte gaat het ook niet in op hoe met abonneren op gebeurtenistypes wordt omgegaan.

Relatie met GDI domeinarchitectuur gegevensuitwisseling

De CloudEvents standaard geeft een invulling aan de volgende principes in de domeinarchitectuur.

Principe	Invulling
Aanbieders kunnen notificeren over belangrijke gebeurtenissen	De standaard zorgt ervoor dat notificaties op een gestandaardiseerde wijze kunnen worden uitgewisseld.
Gegevens worden geleverd vanuit herbruikbare gegevensdiensten	Het aanbieden van notificaties is een manier om gegevens te leveren vanuit herbruikbare gegevensdiensten.

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

Abonneren en notificeren
Ontvangen gegevens

Positionering van de standaard

Relatie met API’s

De mogelijkheid voor afnemers om zich te abonneren op bepaalde gebeurtenistypes kun je realiseren als API. De afnemer ontvangt de notificaties zelf typisch ook via een API. De CloudEvents standaard zegt echter niets over abonneren en maakt het mogelijk om notificaties via allerlei transportprotocollen te versturen.

Toegangsbeveiliging

De standaard zegt niets over de wijze waarop met authenticatie en autorisatie wordt omgegaan. Dat is voor een belangrijk deel ook afhankelijk van het gebruikte transportprotocol. Bij de richtlijnen voor Web Hooks wordt wel aangegeven dat gebruik zou moeten worden gemaakt van OAuth tokens.

Impact van de standaard

De standaard biedt mappings op een aantal transportprotocollen. Je moet daarom contextueel bepalen welk transportprotocol wordt gebruikt, welke inrichtingskeuzes je maakt en welke infrastructuur daarvoor nodig is. Een veelgebruikte combinatie van protocollen is echter HTTP in combinatie met Web Hooks. Er zijn richtlijnen bij de standaard die beschrijven hoe Web Hooks op een gestandaardiseerde wijze kunnen worden gebruikt voor notificaties.

Er is een architectuur voor notificeren in het Federatief Datastelsel in ontwikkeling die handvatten biedt voor het implementeren van notificeren. Deze is gebaseerd op de architectuur die eerder is opgesteld in het VNG project Notificatieservices.

Aandachtspunten

Andere aspecten van notificeren

CloudEvents standaardiseert slechts een deel van de aspecten die relevant zijn voor het ondersteunen van notificeren. Andere belangrijke aspecten zijn het publiceren van gebeurtenistypes en het abonneren op gebeurtenissen. Hiervoor zijn andere standaarden beschikbaar zoals de CloudEvents Subscription standaard, de AsyncAPI standaard en de xRegistry standaard. Overheidsbreed zijn er echter nog geen afspraken gemaakt over dit soort standaarden. Het is daarom voor nu aan organisaties zelf om te bepalen hoe zij deze aspecten inrichten. In de toekomst zou dit gestandaardiseerd kunnen worden.

Soorten gebeurtenissen

Er zijn verschillende categorieën van gebeurtenissen. Een business-gebeurtenis (of 'bedrijfsgebeurtenis') is een gebeurtenis die plaatsvindt binnen een bepaald businessdomein. Een systeem-gebeurtenis is een gebeurtenis die plaatsvindt binnen software- of registratiesystemen. Het is belangrijk om te bepalen welke soort gebeurtenissen ondersteund moeten worden. In het Federatief Datastelsel is uitgangspunt dat notificeren betrekking heeft op business-gebeurtenissen. Dat is tussen organisaties ook het meest relevant om uit te wisselen.

Informatie-arm versus informatierijk

Er zijn twee soorten notificaties: informatiearme en informatierijke. Informatiearme notificaties bevatten weinig informatie over de gebeurtenis, maar kunnen gebruikt worden door afnemers om zelf meer gedetailleerde informatie op te halen. Informatierijke notificaties bevatten alle beschikbare informatie over de gebeurtenis, op basis waarvan afnemers direct over kunnen gaan tot verwerking. Er zijn allerlei afwegingen om tussen informatiearme of informatierijke notificaties te kiezen. In het Federatief Datastelsel is het uitgangspunt dat informatiearm de voorkeur heeft, met name omdat dit het best aansluit bij het principe van data bij de bron. Daarnaast hebben informatierijke notificaties het nadeel dat ze niet goed kunnen omgaan met de privacy van persoonsgegevens.

Relatie met andere standaarden

Relatie met API Design Rules

Omdat het interactiepatroon rondom notificeren afwijkt van het gebruik van API’s zijn ook de API Design Rules niet één-op-één in te zetten. Zo is de OpenAPI specificatie niet goed geschikt voor het beschrijven van gebeurtenistypes. Een aantal richtlijnen zijn wel van toepassing. Denk bijvoorbeeld aan het gebruik van de Nederlandse taal voor interfaces en documentatie, het gebruik van een vaste transitieperiode voor major wijzigingen en het publiceren van een changelog.

Relatie met AsyncAPI

AsyncAPI is een andere standaard voor het omgaan met notificaties. Het is vooral gericht op het beschrijven van gebeurtenistypes en aanbieders van gebeurtenistypes. Het lijkt op de OpenAPI specificatie, maar is specifiek gericht op gebeurtenissen en de interacties bij het uitwisselen van gegevens over gebeurtenissen in de vorm van notificaties. Voor het beschrijven van het gegevensmodel kan net als voor API’s gebruik worden gemaakt van de JSON Schema standaard (maar ook van andere schema standaarden zoals Avro of RAML).

Op deze pagina