vng-realisatie/rawa

Referentiearchitectuur Werken met API's

Met de transitie naar de informatiekundige visie Common Ground gaan gemeenten steeds meer gebruik maken van APIs voor het ophalen en muteren van gegevens in bronregistraties en het ontvangen van notificaties over plaatsgevonden gebeurtenissen. Ook is de verwachting dat gemeenten in toenemende mate zelf APIs gaan aanbieden voor in- en extern gebruik.

Nu een aantal standaard API-specificaties is gerealiseerd en vastgesteld (onder andere Zaakgericht werken (ZGW) en de HaalCentraal API’s voor ontsluiten van basisregistraties) wordt het tijd om deze breed in gebruik te nemen. Gemeenten hebben daarbij aangegeven dringend behoefte te hebben aan een 'kookboek' of referentiearchitectuur waarin is beschreven welke referentiecomponenten nodig zijn en hoe ze moeten worden ingericht om veilig en transparant met API's te kunnen werken. Waarbij er ruimte blijft voor lokaal beleid en er dus verschillende technische implementaties mogelijk blijven.

In het GEMMA Identity en Access Management project wordt door VNG Realisatie samen met een externe kennispartner (SonicBee) gewerkt aan het uitwerken van een referentiearchitectuur voor het veilig en transparant kunnen gebruiken van API's.

Deliverables

Het project Referentiearchtiectuur Werken met API’s is gestart gaat in de eerste helft van het jaar de volgende resultaten opleveren:

• Uitbreiding én aanpassing van de GEMMA modelarchitectuur met referentiecomponenten en bijbehorende functionele afbakening;
• Beschrijving van de meest gerede inrichtingsscenario’s van de verschillende componenten;
• Beschrijving van bestaande (best) practices van gemeenten op de genoemde gebieden;
• Handreiking voor implementatie (alleen wat nodig is ter overbrugging naar API-documentatie).

Project documentatie

De volledige documentatie van de API-standaard is via de standaard Github navigatie beschikbaar via deze link maar kan ook via een gebruiksvriendelijke html interface (Github Pages) worden benaderd.

Status

Het project is in begin februari 2022 gestart. De verwachtte doorlooptijd van de eerste fase van het project is drie tot vier maanden. Het projectteam werkt in sprints van drie weken. De sprintplanning van het project is op deze site te vinden. Na afloop van een sprint worden de resulaten van de sprint in een publiek toegankelijke demo gepresenteerd.

Bijdragen aan het project

Gemeenten en leveranciers worden aangemoedigd om bij te dragen aan het project. Onderstaande links geven informatie over hoe u uw bijdrage kan leveren.

• Hoe u kunt bijdragen
• Omgangsvormen

Beheer en ondersteuning

Contact: [email protected]

Licentie

Copyright © VNG Realisatie 2022 Licensed under the EUPL

rawa's Issues

Hernoeming van de Github repository

De repository van het project is hernoemd van 'AIM' naar 'RAWA'. RAWA staat voor Referentiearchitetuur Werken met API's. De IAM naamgeving van de repository wekte verwarring op aangezien IAM een apart onderdeel is van het werken met API's. Door deze wijziging is de link naar de Github Pages weergave https://vng-realisatie.github.io/RAWA/ geworden en is de oude link naar https://vng-realisatie.github.io/IAM/ niet meer geldig.

Feedback op implementatiescenario

De tekening en de toelichting lijken te stellen dat een API niet zelf verbind naar een policy Engine om een binnenkomend request te valideren. Het lijkt ons logisch, en zinvol, als een API dat wel zelf kan, en dus ook niet perse afhankelijk is van een (centrale) api gateway. In scenario's met een mix van SaaS en on-premise applicaties kan dat zomaar leiden tot meerdere api gateway's.

Het model lijkt uit te gaan van personen als actor, en niet een systeem als actie.
Als dat idd zo is dan staat het bestaande landschap bij gemeenten heel ver af van dit doel; Er zouden dan op zijn minst uitgewerkte (tussen) stappen moeten zijn hoe je hier als gemeente naar toe kunt groeien.
Wat daar ook meespeelt is dat, als er al iets gebeurt aan authenticatie, het nu is op basis van mTLS, waarbij systemen zich authenticeren. Systemen die bij aanroepen van api's context over de user die een actie in gang zet kennen we nog niet. Daarnaast zullen er altijd acties zijn die door systemen geïnitieerd worden. Hoe worden de rechten van een systeem gevat in een policy Engine model?
De stap van dat (mTLS) model naar dit model is enorm en niet in 1x te zetten.

We denken dat een model met een Policy Engine de toekomst is, maar er is een gelaagder pad nodig (bv eerst een api gateway icm mTLS, dan een eerste stapje naar een PE, dan een of twee api's die obv oAuth ontsloten worden, dan ingewikkelder rules) om er te komen.