De beschikbaarheid van publieke adres- en gebouwgegevens heeft door de jaren heen een flinke evolutie doorlopen. Vóór de BAG had elke gemeente meerdere adresregistraties en dat maakte gegevensuitwisseling lastig. Met de BAG kwam daar verandering in: één centrale registratie, beheerd door het Kadaster en onderhouden door gemeenten. Dit maakte de uitwisseling van deze gegevens al een stuk eenvoudiger. Ook verschillende externe partijen gingen de BAG gebruiken, zoals TomTom en Esri, een bekende softwareleverancier voor GIS (Geografische Informatiesysteem). Met de komst van API's kwam het gebruik van de BAG in een stroomversnelling.

Verschillende wegen naar dezelfde data​

Janette Storm, productmanager BAG bij het Kadaster, is al sinds de invoering van de wet BAG in 2009 betrokken bij deze basisregistratie. De BAG werd in die tijd vooral gebruikt via bestanden en via een voorloper van de huidige webapplicatie BAG-Viewer. "Als je destijds een losse vraag wilde stellen, dan deed je dat in de BAG-Viewer. Als je veel administratieve data wilde hebben, dan haalde je gewoon het hele bestand op. Er zijn nog steeds gebruikers die dat elke maand doen", vertelt Storm. Er was ook een zogeheten SOAP-webservice beschikbaar waarmee je gegevens in XML-formaat kon opvragen, maar deze was volgens Storm best bewerkelijk om te implementeren. Dit bleek beter te kunnen met API's.

Een gouden toevalstreffer​

Rond 2017 werkte het Kadaster aan een dataplatform op basis van linked data. De BAG-API ontstond volgens Storm eigenlijk als bijproduct van dit project. Ze vertelt hierover: "De techneuten gaven aan dat we de gegevens ook vrij makkelijk via een API konden publiceren. Daar was interesse in, maar dan wilden we het ook meteen goed doen: volgens de geldende API-standaarden, een goede manier van publiceren en makkelijk toegankelijke specificaties."

Die aanpak bleek ontzettend succesvol. Binnen een paar maanden nadat de BAG-API live ging, kreeg deze al net zoveel aanroepen als de SOAP-webservice, die op dat moment al meer dan acht jaar in gebruik was. Geïnteresseerde eindgebruikers wisten de API zelf te vinden en vroegen om aansluiting. Als bijzondere opsteker won het Kadaster er in 2019 de Gouden API mee, de prijs voor de beste overheids-API.

Van bijproduct naar eindproduct​

Vlak na de introductie van de API volgde een grote herziening van de BAG. Storm: "Dat was ook het moment om te kijken welke dataproducten we moesten laten bestaan, welke een upgrade moesten krijgen en wat we hetzelfde moesten houden. De eerste reactie vanuit de gebruikers was dat ze alles wilden behouden én dat er behoefte was aan een API." Het eerste wat opviel was dat veel gebruikers nog niet wisten dat er al een API was. Voor Storm was dit het signaal om de BAG-API van bijproduct naar een eindproduct te brengen en de oude SOAP-webservice niet verder te ontwikkelen.

Kijken met de bril van de eindgebruiker​

Bij versie 2 van de BAG-API verschoof de focus van pure technische ontsluiting naar een betere bruikbaarheid voor de eindgebruiker. Met haar achtergrond als industrieel ontwerper weet Storm als geen ander dat bruikbaarheid de sleutel is tot succes. "Een belangrijke stap was om te kijken welke informatie de eindgebruiker daadwerkelijk nodig heeft. Wat we dus bijvoorbeeld bij versie 2 van de API hebben gedaan, is dat je niet alleen een adres kan opvragen, maar ook de eigenschappen die bij dat adres horen. Dit was bij de eerste versie van de API een hoop gepuzzel", vertelt Storm.

Geen gepuzzel meer​

Toen versie 2 van de BAG-API, de BAG API Individuele Bevragingen (IB), uitkwam, nam het gebruik opnieuw een enorme vlucht. Ondanks dit nieuwe succes maakte niet iedere gebruiker het meest efficiënte gebruik van de BAG-API. Storm noemt als voorbeeld een ontwikkelaar die duizenden losse bevragingen deed voor adresgegevens per pand, omdat hij niet wist dat er een efficiëntere, samengestelde route bestond. Zulke pieken in het dataverkeer zijn voor het Kadaster reden om contact op te nemen met gebruikers, en dat leverde een interessant patroon op: veel van dit soort problemen bleken terug te voeren op hoe de documentatie was opgebouwd. Veel gebruikers volgden die top-down, terwijl de meest bruikbare functionaliteit onderaan stond. Storm: "Toen hebben we de documentatie daarop aangepast. Nu staat de functionaliteit die het handigst is om te gebruiken bovenaan. Deze functies werden toen al het meest gebruikt, en nu nog steeds. 90% van de aanvragen is namelijk samengestelde informatie."

De volgende stap​

Het Kadaster staat op dit moment voor een verplichte technische wijziging in de backend. Voor Storm reden om gelijk verder te kijken, want de tweede versie van de API is inmiddels ook al meer dan vijf jaar oud. Voor versie 3 van de API gaat het deze keer niet zozeer om ingrijpende wijzigingen. "We hebben heel lang gezegd: we moeten het zo ontwerpen dat het product aansluit bij de vraag. Nu zeg ik eigenlijk: dat lukt best wel goed, maar we willen de kans dat je de data echt goed kan gebruiken nog groter maken", vertelt Storm. "Functioneel zal het bijvoorbeeld makkelijker worden om ook de historie, historische informatie, op te vragen. En dat alles zoveel mogelijk via hetzelfde endpoint gaat, zodat je niet op iets anders hoeft aan te sluiten om aan deze gegevens te komen."

Ook geografische data delen via API's​

Naast de BAG-API IB werkt het Kadaster ook aan andere manieren om de BAG-data via API's te ontsluiten. Dit jaar is bijvoorbeeld de BAG OGC Features API gelanceerd. Deze API is gericht op bevragingen van de BAG door GIS-specialisten; de geografische informatie staat centraal in plaats van de administratieve gegevens van het object.

Samenwerken aan betere overheids-API's​

De ontwikkeling van de BAG-API staat niet op zichzelf. Samen met andere partijen werkt het Kadaster in het Kennisplatform API's aan gezamenlijke standaarden voor overheids-API's, waaronder de API Design Rules. "We willen dat onze API-ontwikkeling afgestemd is met het kennisplatform, zodat we allemaal dezelfde richting opgaan", vertelt Storm. Om deze aanpak te stimuleren, reikt het kennisplatform elk jaar de Gouden API uit: de prijs voor de beste overheids-API van dat jaar. Dit jaar ligt de focus op de implementatie van diverse API's. Storm: "Als je kijkt naar de BAG-Viewer, dan is dat een goed voorbeeld. Het is de implementatie van de BAG-API IB, de BAG OGC API's en bijvoorbeeld ook de Terugmeldings-API." Het Kadaster laat hiermee zien dat het niet alleen goede API's bouwt, maar ze ook zelf weet te combineren tot waardevolle applicaties.

Productgericht blijven ontwikkelen​

In veel opzichten is de BAG-API een rolmodel geweest voor andere overheids-API's en valt er veel te leren uit de aanpak van het Kadaster. Storm: "De focus van technische ontsluiting naar productgericht ontwikkelen, is denk ik een stap die op veel plekken in de overheid nog wel gemaakt moet worden. En door zichtbaar te maken van wat goed werkt, kun je ook anderen inspireren en stimuleren."

In de eerste drie delen van deze serie hebben we GraphQL leren kennen als een getypeerde querytaal met een fundamenteel ander model dan REST (deel 1), zagen we dat de flexibele bevraging zowel de grote kracht als een serieuze beheeropgave is (deel 2) en liepen we zes ontwerpuitdagingen langs die in de praktijk bepalen hoeveel werk een GraphQL-API werkelijk kost (deel 3).

In dit slotdeel komen we bij de vraag waar het allemaal om draait: wanneer is GraphQL een passende keuze, en wanneer ben je met REST beter af? Er zijn omstandigheden waarin het ene model aantoonbaar beter past dan het andere.

Het afwegingskader​

De uitdagingen uit deel 2 en 3 vormen de opgave die GraphQL met zich meebrengt. De vraag is per situatie of die opgave in verhouding staat tot wat je ervoor terugkrijgt. Zeven factoren helpen bij die afweging. Sommige gaan over omstandigheden die je niet zelf in de hand hebt, andere over hoeveel werk je erin wil stoppen; hoe zwaar ze wegen, hangt van je situatie af.

De kolommen sluiten elkaar niet uit. GraphQL en REST kunnen naast elkaar bestaan, elk voor het deel van het landschap waar ze sterk zijn. Bij publieke overheids-API's wijzen de eerste drie rijen vaak dezelfde kant op, en dan is REST het uitgangspunt. Vaak is niet altijd: bedien je clients waarmee je direct kunt afstemmen, buiten het ketenverkeer en zonder cachingafhankelijkheid, dan komt de afweging er anders uit, en blijven de vier andere rijen te beantwoorden.

Vier rijen verdienen een toelichting.

Afnemers. Het beheersapparaat uit deel 2 gaat uit van afnemers die je kunt identificeren: kostenbudgetten per afnemer, vooraf geregistreerde operaties, monitoring per client. Bij anonieme afnemers vervalt die aanname en moeten de generieke limieten al het werk doen, zonder onderscheid tussen een afnemer die zich vergist en een afnemer die het erom doet.

Bekend is hier niet hetzelfde als gecontracteerd. Ook ketenverkeer loopt tussen bekende partijen, bijvoorbeeld via FSC, maar daar liggen de koppelingen vast in afspraken per organisatie, gaat het om een stabiele set gegevensvragen en hoort er een verantwoordingsplicht bij. Die situatie wijst richting REST, zoals de sectie over de overheidscontext hieronder uitwerkt. Deze rij gaat over afnemers met wie je in hetzelfde ontwikkelritme zit en die hun vragen zelf willen samenstellen.

Kader. Hier speelt een misverstand. Het functioneel toepassingsgebied van de REST API Design Rules is "het aanbieden van REST API's", en Forum Standaardisatie stelt er expliciet bij dat de standaard "niet het gebruik van REST-API's verplicht". Kies je GraphQL, dan val je dus buiten het toepassingsgebied: je mist een vastgesteld kader en de bijbehorende toetsing, zoals de ADR Checker die een OpenAPI-document tegen de regels houdt, en hoeft tegelijk niets uit te leggen. Voor een API die je eigen frontend bedient is dat weinig bezwaar; in ketenverkeer of als landelijke voorziening is het de kern van de afweging.

Bevragingen. Tel je bevragingen, en vraag wie ze definieert. Een stabiele set gegevensvragen laat zich prima als toegesneden endpoints of informatieproducten aanbieden, en dat is standaardconform. Een generiek querymechanisme betaalt zich terug wanneer de vragen talrijk zijn, snel wisselen en door de clientteams zelf worden bedacht. Zet je die vragen vervolgens vast als geregistreerde operaties (de persisted queries uit deel 2), dan heb je feitelijk weer endpoints, met dit verschil: de clientteams definiëren ze zelf, zonder wijziging aan de backend.

Omkeerbaarheid. Deze ontbreekt in de meeste afwegingen en is voor de overheid juist relevant. Deel 3 liet zien dat het dialect voor filtering en sortering per framework verschilt en daarmee in je publieke contract landt, en dat custom scalars server en client aan dezelfde library binden. Het contract erft daarmee eigenschappen van de implementatie, wat een latere migratie of leverancierswissel duurder maakt. Houd je schema daarom technologieneutraal en laat het dialect niet naar buiten lekken. Dat is ook waar de leidraad Gebruik open standaarden op aandringt: leveranciersonafhankelijkheid begint bij een contract dat niet aan één implementatie vastzit.

Hoe grote aanbieders kiezen​

Dat de afweging echt twee kanten op kan vallen, laat de praktijk van grote API-aanbieders zien.

Shopify ging volledig over: de REST Admin API is sinds oktober 2024 legacy en nieuwe publieke apps in de App Store moeten sinds april 2025 GraphQL gebruiken. Duizenden bekende, geregistreerde app-ontwikkelaars met sterk uiteenlopende databehoeften op één samenhangend commerce-datamodel, en de schaal om cost-based rate limiting (zie deel 2) als platformvoorziening aan te bieden.

Netflix draait intern federated graphs over ruim tweehonderd services: supergraphs, samengesteld uit de deelschema's van evenzoveel teams, met volledige controle over alle clients.

GitHub biedt al jaren REST en GraphQL naast elkaar aan en adviseert afnemers te kiezen wat bij hun gebruik en ervaring past: REST vanwege de vertrouwde HTTP-conventies, GraphQL wanneer één query het werk van meerdere REST-requests moet doen.

Tegelijk klinkt er ook kritiek uit de praktijk. Matt Bessey vatte in Why, after 6 years, I'm over GraphQL samen waarom hij na zes jaar GraphQL voor nieuw werk weer een OpenAPI-gebaseerde REST-API adviseert: het beveiligings- en performance-oppervlak uit deel 2 bleek in de praktijk duurder dan de flexibiliteitswinst. Marc-André Giroux, die jarenlang aan de API-platformen van GitHub en Netflix werkte, komt in Why, after 8 years, I still like GraphQL sometimes in the right context tot een voorwaardelijk ja: GraphQL loont bij veel bekende clients en een rijk datamodel, en is overkill daarbuiten.

Deze verhalen spreken elkaar niet tegen: de uitkomst volgt telkens uit de context, niet uit de technologie. Belangrijk is dan wel welke context dat is. Het zijn platformen met duizenden geregistreerde ontwikkelaars op één commercieel datamodel, met een platformteam dat limieten en schemabeheer als product aanbiedt. Geen van hen is een publieke registratie met een wettelijke taak en een verantwoordingsplicht over inzage. En binnen de Nederlandse overheid is de bewijsbasis dun: breed gedeelde ervaringsverhalen zijn er nauwelijks. Weeg deze casussen dus op overdraagbaarheid naar jouw situatie, niet op autoriteit.

De Nederlandse overheidscontext​

Voor overheidsorganisaties speelt naast de technische afweging een standaardenafweging.

De REST API Design Rules staan sinds 2020 op de 'pas toe of leg uit'-lijst van het Forum Standaardisatie en zijn expliciet gescoped op REST-API's. De API Strategie van de Nederlandse overheid noemt GraphQL alleen zijdelings als mogelijke query style. Er is dus geen NLGov-profiel, geen toetsingskader en geen vastgestelde set conventies: wat de ADR voor REST-API's dichtregelen, zou per organisatie opnieuw worden uitgevonden, met interoperabiliteitsrisico's van dien, terwijl deel 3 liet zien dat juist die conventies (paginering, filtering, foutafhandeling, en zelfs het ankerpunt voor autorisatie) bij GraphQL niet vanzelf meekomen. De vraag hoe de ADR zich verhouden tot alternatieven zoals GraphQL staat binnen het Kennisplatform API's al langer op de agenda, en werd in juni 2026 opnieuw opgepakt. Het API-register op deze site is om die reden REST-only: GraphQL heeft potentie, maar verdient pas een eigen plek bij bredere adoptie en standaardisatie.

Naast het API-ontwerp is er de verbindingenkant: FSC (Federated Service Connectivity), verplicht onderdeel van het Digikoppeling REST API-profiel, sinds april 2026 in versie 2.0. De FSC-specificatie definieert een service als "An HTTP API offered to the Group" en stelt geen eisen aan de API-stijl, dus technisch kan GraphQL erop, maar inhoudelijk wringt de granulariteit. Contracten autoriseren een service als geheel en het transactielog registreert per request welke service is bevraagd. Een REST-landschap laat zich opdelen per resource of gegevensdomein; een GraphQL-API is in de praktijk één service. Contracten worden daarmee alles-of-niets, en de vraag welke gegevens zijn ingezien is alleen in de GraphQL-laag te beantwoorden. Die verantwoordingsopgave organiseer je dus zelf, en het per-operatie-anker uit deel 3 is daarvoor de kansrijkste route: een vastgezette set geregistreerde operaties laat zich per stuk autoriseren en loggen, met het Logboek Dataverwerkingen als kader voor de vastlegging. Dat gebeurt dan wel buiten de contracten en het transactielog van FSC om.

REST-landschap op FSC          GraphQL op FSC
├─ vergunningen (contract A)   └─ graphql (één contract:
├─ dossiers     (contract B)      alles-of-niets)
└─ documenten   (contract C)

Waar GraphQL wél past binnen de overheid​

Betekent dit dat GraphQL binnen de overheid geen plaats heeft? Nee. Het betekent wel dat GraphQL vooralsnog niet de gestandaardiseerde, publieke API-laag zelf vervangt, maar kansrijk is waar de afnemers bekend zijn, want dan valt het aanvalsoppervlak uit deel 2 grotendeels weg: als laag boven de bronnen, of als toegang tot een intern of afgeschermd model. Het eerste schematisch:

Concreet zien we twee patronen:

• Een laag boven bestaande bronnen. In de kleinste vorm een backend-for-frontend: een GraphQL-laag die voor de eigen portalen en apps data uit meerdere (REST-)bronnen samenbrengt, met clients die bekend zijn en in eigen beheer. In de bredere vorm een orkestratielaag die gegevens uit meerdere API's in samenhang aanbiedt aan meerdere afnemers, zonder die bronnen te vervangen. Het Nederlandse voorbeeld daarvan is IMX van Geonovum: model-gedreven orkestratie waarbij een doelmodel (het informatieproduct) wordt gemapt op bestaande bronregistraties. GraphQL zit daar vooral onder de motorkap: het georkestreerde informatieproduct kan ook als REST-API worden ontsloten, en de bronnen blijven gewone, ADR-conforme REST-API's of OGC API's.
• Toegang tot één samenhangend model. Veel bekende afnemers die uiteenlopende en wisselende vragen stellen: interne teams in een groot datalandschap, waar de federated aanpak van Netflix als voorbeeld kan dienen, of externe afnemers die zich registreren en verkennende, analytische bevragingen doen op rijke datasets, vergelijkbaar met de analytische use cases waar we bij OData dezelfde grens trokken: onderzoek en zelfbediening op datasets, niet het primaire kanaal voor wettelijke gegevensverstrekking. Hier is GraphQL niet de laag boven de bronnen maar de toegang tot het model zelf, en gelden de rijen Bevragingen en Beheersing uit het afwegingskader in volle omvang.

Bij het eerste patroon hoort een voorbehoud: een extra laag is een extra contractvlak. Betekenis, autorisatie en logging moeten daar opnieuw worden waargemaakt, en bij model-gedreven orkestratie is de mapping zelf de plek waar semantiek kan sneuvelen. Wat je wint aan gemak voor de afnemer, organiseer je erbij aan beheer. Dat is niet nieuw en niet GraphQL-specifiek: we schreven eerder over de uitdagingen bij API-orkestratie.

Voor publieke API's met anonieme afnemers, open data met zware caching, en voor ketenverkeer, landelijke voorzieningen en andere ontsluiting waar de conventies tussen organisaties vast moeten liggen, blijft REST de logische keuze.

Wat de keuze voor GraphQL vraagt​

Valt de afweging naar GraphQL, dan is dit de inrichting die deel 2 en 3 opleveren. Omdat er geen profiel is dat dit voor je regelt, is dezelfde lijst ook wat je zelf vastlegt en publiceert, richting je eigen architectuurboard, je security review en je afnemers.

Deze acht punten zijn het minimum, geen bewijs dat GraphQL past. Ze maken je eigen API beheersbaar, maar interoperabiliteit vraagt conventies die je met anderen deelt, en die komen uit een profiel dat voor GraphQL niet bestaat. Die vraag beantwoordt het afwegingskader hierboven. Autorisatie laat zich daarbij het minst goed achteraf toevoegen, omdat het elk veld en elk pad door de graph raakt (deel 3).

Vooruitblik​

De standaardisatie rond GraphQL beweegt, en dat is relevant voor deze afweging op langere termijn. Wie de afweging over een of twee jaar opnieuw maakt, kan op deze signalen letten:

• De GraphQL over HTTP-specificatie wordt definitief: daarmee ligt het transportgedrag vast en wordt ondersteuning door gateways en tooling betrouwbaarder.
• De RFC voor persisted operations landt in die specificatie: dan is er één gestandaardiseerde vorm voor het begrenzen, cachen en autoriseren van bevragingen, nu nog per implementatie anders (deel 2 en 3).
• IBM's cost-directives groeien uit tot een gedeelde taal voor querykosten, zodat limieten interoperabel worden in plaats van servereigen.
• De Composite Schemas-werkgroep levert een leveranciersneutrale federatiestandaard op, relevant voor orkestratie over organisatiegrenzen en voor de omkeerbaarheid uit het afwegingskader.
• En dichter bij huis: de eerdergenoemde discussie binnen het Kennisplatform API's leidt tot een standpunt of profiel, en GraphQL-API's verschijnen in relevante aantallen in het API-register.

Naarmate deze punten worden afgevinkt, verschuift de balans: een deel van wat je nu zelf moet ontwerpen en bewaken, wordt dan door standaarden en tooling gedragen. Het is dezelfde ontwikkeling die REST in de afgelopen tien jaar heeft doorgemaakt, met de ADR als resultaat.

Het kan ook anders lopen. De RFC voor persisted operations ligt er al jaren, de transportspecificatie is nog altijd een working draft, en het OpenAPI-ecosysteem staat evengoed niet stil. Reken dus niet op standaardisatie die er nog niet is: de afweging die je vandaag maakt, moet standhouden op wat vandaag vastligt.

Werkgroep GraphQL​

Op die standaardisatie hoeft de overheid niet passief te wachten. Voor asynchrone API's doorloopt de werkgroep AsyncAPI op dit moment een verkenningstraject; een vergelijkbare werkgroep voor GraphQL zou nu al aan de slag kunnen.

De eerste taak is dan niet het schrijven van regels, maar het definiëren van het toepassingsgebied, en dat is minder triviaal dan het lijkt. De ADR gelden voor "het aanbieden van REST API's" en de OAS voor "het beschrijven/specificeren van een REST API": beide zijn gescoped op de techniek. Daarmee regelen ze hoe je iets bouwt zodra de keuze gemaakt is, en niet wanneer die keuze passend is. Een GraphQL-profiel met "het aanbieden van GraphQL API's" als toepassingsgebied herhaalt die cirkel, en dan valt de keuze tussen de twee opnieuw tussen de kaders in. Wie dat wil doorbreken, moet het toepassingsgebied formuleren in termen van de opgave in plaats van de technologie: naar het soort afnemers, of naar het soort ontsluiting. Dat is precies de vraag die bij het Kennisplatform op de agenda staat, en ze is lastiger dan het opschrijven van conventies.

Pas daarna komen de regels in beeld, en die inhoudsopgave ligt in deze serie al klaar: van limieten en caching in deel 2 tot paginering, foutafhandeling en het ankerpunt voor autorisatie in deel 3, precies de onderdelen waar de ADR dit voor REST-API's al regelen.

Slotadvies​

GraphQL is een volwassen technologie die een reëel probleem oplost: het flexibel bedienen van veel verschillende, bekende clients vanuit één samenhangend datamodel. Wie in die situatie zit en bereid is de bijbehorende beheer- en ontwerpopgave serieus te nemen, heeft aan GraphQL een krachtig instrument, ook binnen de overheid, bijvoorbeeld als backend-for-frontend of in een intern datalandschap.

Voor publieke overheids-API's ligt dat anders. Daar wegen de sterke punten van REST (eenvoud, HTTP-native caching, de route als ankerpunt voor autorisatie, content negotiation) zwaar, en bieden de ADR een vastgesteld, getoetst kader dat voor GraphQL vooralsnog ontbreekt. Niet omdat GraphQL slechter is, maar omdat de context er (nog) niet naar is. De ADR maken die keuze niet voor je, want ze gelden alleen als je REST aanbiedt. Wie GraphQL kiest hoeft dus niets uit te leggen, maar stapt wel buiten een vastgesteld kader en belegt de acht punten hierboven zelf. Voor het bedienen van de eigen frontends is GraphQL een serieuze optie om te verkennen. En wie over een paar jaar opnieuw kijkt, loopt de zeven factoren nog eens langs: staat er dan een profiel, dan verandert vooral de rij "Kader", en dat is het echte nieuws.

Een compacte referentie over GraphQL, met de status binnen de overheid en de belangrijkste specificaties, staat in de kennisbank.

Je bouwt aan een nieuwe applicatie, koppelt systemen via API's of werkt aan een voorziening voor de overheid. En ergens onderweg komt de vraag langs: welke open standaarden moet ik hier nu eigenlijk toepassen? Ze zijn niet vrijblijvend. Voor publieke organisaties zorgen open standaarden voor interoperabiliteit, leveranciersonafhankelijkheid, veiligheid, datakwaliteit en toegankelijkheid. Precies de dingen die bepalen of jouw software straks soepel samenwerkt met de rest van het overheidslandschap.

Het lastige is alleen: de standaarden zíjn er, de afspraken zíjn helder, maar uitzoeken wélke gelden voor jouw specifieke applicatie kost tijd die je liever in code steekt. Daardoor blijft de toepassing in de praktijk achter, niet uit onwil maar uit gedoe.

De Beslisboom Open Standaarden​

Voor dat moment is er de Beslisboom Open Standaarden van Forum Standaardisatie. In zes stappen kom je tot een gerichte selectie van de standaarden die voor jouw project relevant zijn. Je loopt de vragen door en ziet meteen welke standaarden ertoe doen.

Het resultaat is geen afvinklijstje, maar een onderbouwde set die je direct kunt vertalen naar je ontwerp, je backlog of je gesprek met de architect of leverancier. Een paar minuten werk aan het begin scheelt later een hoop refactoren en discussie.

Bekijk de video Beslisboom Open Standaarden →

Handig om bij de hand te hebben​

• Informatieveiligheid: veel overheidsorganisaties passen de BIO toe (gelijkwaardig aan ISO 27001/27002). De ICO Wizard van het CIP helpt je de juiste veiligheidsnormen tijdig in beeld te krijgen, zodat ze niet achteraf in je eisen hoeven te worden gepropt.
• Voorbeelden uit de praktijk: in de Monitor Open Standaarden zie je hoe andere projecten standaarden hebben toegepast. Die data is ook ontsloten via de NORA.

Van afspraak naar code​

Standaarden afspreken is één ding; ervoor zorgen dat ze nageleefd worden in je software is een vak apart. Gebruik daarom de beslisboom om uit te vinden welke standaarden van toepassing zijn op jouw project, en check welke tooling er beschikbaar is voor welke standaard.

Direct naar de Beslisboom →

In deel 2 zagen we dat de flexibiliteit van GraphQL een beheeropgave met zich meebrengt. In dit deel kijken we naar de ontwerpkant. De rode draad: veel zaken die je in REST oplost met mechanismen van HTTP (headers, statuscodes, media types, middleware op routes) moeten in GraphQL expliciet gemodelleerd worden in het schema en de resolvers. Dat maakt schema's en queries complexer dan de voorbeelden uit deel 1 doen vermoeden. We behandelen zes uitdagingen die je in vrijwel elk GraphQL-project van enige omvang tegenkomt.

1. Paginering laat het schema groeien​

Elk lijstveld heeft paginering nodig; dat leerde deel 2 al. De de-facto standaard hiervoor is de GraphQL Cursor Connections-specificatie uit Facebooks Relay-framework, aanbevolen in de officiële GraphQL-documentatie. Kijk wat er met ons schema uit deel 1 gebeurt:

# Vóór: eenvoudig, maar onbegrensd
type Organisatie {
  apis: [Api!]!
}

# Ná: Cursor Connections
type Organisatie {
  apis(first: Int, after: String): ApiConnection!
}

type ApiConnection {
  edges: [ApiEdge!]!
  pageInfo: PageInfo!
}

type ApiEdge {
  node: Api!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  endCursor: String
}

Drie extra types voor één lijstveld (en dan is PageInfo hier nog vereenvoudigd: de spec vereist ook hasPreviousPage en startCursor), en elke query wordt navenant dieper:

{
  organisatie(id: "min-bzk") {
    apis(first: 20, after: "Y3Vyc29yOjIw") {
      edges {
        node { titel versie }
      }
      pageInfo { hasNextPage endCursor }
    }
  }
}

Ter vergelijking: in REST is hetzelfde doorgaans twee queryparameters (?page=2&per_page=20 of een cursor) en een Link-header. Ook dat is geen universeel gegeven (er bestaan page-, offset- en cursorvarianten, en profielen zoals de ADR bestaan juist om die keuze uniform te maken), maar het verschil zit in wáár de complexiteit landt: bij REST in parameters en headers, bij GraphQL in de structuur van schema en query. De Connections-structuur heeft goede redenen (stabiele cursors, metadata per resultaat), maar het patroon herhaalt zich voor élk lijstveld, en wie totalen of facetten toevoegt, ziet de envelope verder groeien.

2. Het standaardisatie-misverstand​

Een hardnekkig misverstand is dat GraphQL zaken als filtering, sortering en zoeken "standaard oplost". In werkelijkheid standaardiseert de specificatie de taal (syntax, typesysteem, executie), maar vrijwel geen conventies daarbovenop. De Cursor Connections-spec uit de vorige paragraaf is vrijwel de enige breed gedragen conventie, en zelfs die is formeel geen onderdeel van de GraphQL-specificatie.

Filtering en sortering zijn daardoor in elk framework anders vormgegeven. Dezelfde vraag (actieve API's waarvan de titel "register" bevat, alfabetisch gesorteerd) in twee populaire servers:

# Hasura
{
  apis(
    where: { status: { _eq: "actief" }, titel: { _ilike: "%register%" } }
    order_by: { titel: asc }
  ) { titel }
}

# HotChocolate (.NET)
{
  apis(
    where: { status: { eq: "actief" }, titel: { contains: "register" } }
    order: [{ titel: ASC }]
  ) { titel }
}

Vergelijkbare maar nét andere dialecten bestaan voor PostGraphile, Prisma-gebaseerde servers en andere frameworks. Wie, zoals in deel 2 beschreven, voor zo'n framework kiest vanwege de efficiënte vertaling naar SQL, neemt het dialect op de koop toe: de serverkeuze werkt direct door in het publieke contract van de API. Voor één project is dat overkomelijk, maar in een landschap waarin API's van verschillende organisaties op elkaar moeten aansluiten, zoals binnen de overheid, zijn kennis en tooling zo niet zonder meer overdraagbaar. Ook in REST komen zulke conventies niet uit de standaard zelf; daarvoor bestaan profielen als de REST API Design Rules. Een vergelijkbaar afsprakenkader bestaat voor GraphQL nog niet.

3. Union types en foutafhandeling​

Sommige velden kunnen meerdere types opleveren. Denk aan een zoekfunctie over het register die zowel API's als organisaties vindt; in GraphQL modelleer je dat met een union:

union ZoekResultaat = Api | Organisatie

type Query {
  zoek(term: String!): [ZoekResultaat!]!
}

De client moet vervolgens per mogelijk type een inline fragment schrijven en op het metaveld __typename dispatchen:

{
  zoek(term: "adressen") {
    __typename
    ... on Api { titel versie }
    ... on Organisatie { naam }
  }
}

Dat werkt, maar het dispatch-werk ligt bij de client: elke afnemer, in elke taal, moet dit patroon implementeren. In REST blijft hetzelfde probleem doorgaans buiten het contract: aparte endpoints per resourcetype, of een expliciet typeveld in de response.

Foutafhandeling maakt het verschil het scherpst zichtbaar. GraphQL-responses komen vrijwel altijd terug met HTTP-status 200 OK, ook als er iets misging; fouten staan in een aparte, generieke en ongetypeerde errors-lijst in de body. Voor "niet gevonden" volstaat een nullable veld (zoals organisatie in deel 1), maar voor verwachte foutsituaties die zelf informatie dragen, wordt ditzelfde union-mechanisme ingezet: het patroon errors as data, geïntroduceerd door Sasha Solomon in "200 OK! Error Handling in GraphQL", met dezelfde dispatch-plicht voor de client als gevolg. REST gebruikt hiervoor statuscodes met een application/problem+json-body: gestandaardiseerd (RFC 9457) en zonder extra schemawerk.

4. Custom scalars: coupling aan beide kanten​

Het typesysteem van GraphQL kent standaard vijf scalars: Int, Float, String, Boolean en ID. Een datumtype ontbreekt bijvoorbeeld. Voor alles daarbuiten definieer je custom scalars, en daar wringt het. Een scalar is voor de GraphQL-runtime een black box: het schema zegt niets over de structuur, dus serialisatie en validatie moeten aan de server- én clientkant met dezelfde afspraken (en meestal: dezelfde library) worden geïmplementeerd. Daarmee ontstaat coupling buiten het typesysteem om.

Geodata maakt het probleem goed zichtbaar. Een GeoJSON-geometrie is in standaardtypes praktisch niet uit te drukken: coördinaten van een polygon zijn lijsten van lijsten van lijsten, en GraphQL kent geen generieke JSON-structuren. De praktijk is daarom vrijwel altijd een custom scalar die een JSON-blob doorlaat:

scalar GeoJSON
  @specifiedBy(url: "https://datatracker.ietf.org/doc/html/rfc7946")

type Gebouw { id: ID! geometrie: GeoJSON! }

Voor dit veld, waar structuur juist belangrijk is, valt de typering dus weg. Er bestaan hulpmiddelen: @specifiedBy verwijst naar een externe specificatie, de graphql-scalars-library biedt kant-en-klare scalars (waaronder GeoJSON) en de GraphQL Foundation host een register van scalar-specificaties. Ze maken de afspraak vindbaar en het werk kleiner, maar de coupling blijft: @specifiedBy is een verwijzing voor ontwikkelaars en geen instructie die de runtime uitvoert, en server en client hebben nog steeds elk een implementatie nodig die dezelfde interpretatie volgt. Wijken server en client in library of versie van elkaar af, dan keurt het schema de waarde alsnog goed en komt de fout pas boven bij het interpreteren van de data.

5. Autorisatie verliest zijn ankerpunt​

In REST valt autorisatie vaak samen met de resource en de route, bijvoorbeeld met OAuth 2.0-scopes per endpoint. Eén regel in een middleware of API-gateway dekt een heel endpoint:

GET /apis/{id}           → publiek
GET /apis/{id}/notities  → alleen rol BEHEERDER

In GraphQL bestaat die route niet: elk veld is bereikbaar via willekeurig veel paden door de graph, via api(id: ...), via organisatie { apis { ... } } of via een zoekresultaat. Het ankerpunt waaraan je een regel ophangt, kies je dus zelf: het veld of de operatie.

Per veld. Gangbaar zijn checks in resolvers en schema-directives zoals @auth:

type Api {
  interneNotities: String @auth(requires: BEHEERDER)
}

De specificatie kent zo'n directive niet. Autorisatie komt in GraphQL zelf helemaal niet voor, dus elke server en gateway kiest een eigen vorm. Wat er wel is, is advies: de officiële documentatie raadt aan de logica onder de resolvers in de businesslaag te leggen, zodat de GraphQL-laag zelf geen regels bevat die je kunt vergeten. Lastig blijft de context, want hetzelfde veld kan per pad andere regels vragen: een e-mailadres dat de eigen beheerder mag zien, hoort niet in een zoekresultaat. Een eigen type per context lost dat op en laat het schema opnieuw groeien. En foutgevoelig is het: in november 2025 publiceerde Apollo twee security advisories waarbij de compositielogica van federated schema's field-level access control liet omzeilen. Autorisatie per veld over een graph kent intrinsiek meer edge cases dan per route, zeker als die graph over meerdere services is verdeeld.

Per operatie. Wie met persisted queries werkt (deel 2), heeft weer een eindige, benoemde set operaties en kan rechten per document toekennen, functioneel gelijk aan scopes per endpoint. De handhaving schuift daarmee naar voren, naar een toets vóór executie, en omdat een vast document ook het pad vastlegt, wordt het e-mailadres uit het voorbeeld hierboven vooraf toetsbaar. Ook hier is de vorm niet gestandaardiseerd: de persisted operations-RFC uit deel 2 is nog een voorstel.

Geen van beide ankers dekt de gegevens zelf. Een document organisatie(id: $id) legt vast welke vorm een afnemer mag opvragen, niet welke organisaties hij mag zien. Staat de identificatie in een variabele, dan kan een policy enforcement point die aan een centraal policy decision point voorleggen, net als bij een pad-parameter in REST. Komen de objecten pas uit de traversal, zoals bij een lijst of een geneste relatie, dan valt er vóór executie niets te beoordelen. De praktijk is dus een combinatie die je zelf ontwerpt: het grofmazige deel aan de voordeur, het gegevensafhankelijke deel onder de resolvers.

6. Content negotiation past niet in het model​

REST kent een gestandaardiseerd mechanisme om dezelfde resource in meerdere formaten aan te bieden: content negotiation via de Accept-header.

GET /gebouwen/0363100012345678 HTTP/1.1
Accept: application/geo+json

Dezelfde URL kan zo plain JSON, GeoJSON, XML of bijvoorbeeld een Verifiable Credential opleveren, zonder dat het API-ontwerp verandert. GraphQL kent dit mechanisme niet: er is één responsevorm, gedicteerd door het schema. Alternatieve representaties moeten dus in het schema zelf worden gemodelleerd, als extra velden (gebouw { alsGeoJSON }), aparte queries of custom scalars. Zo sijpelen formaatdetails door in wat een representatie-onafhankelijk datamodel zou moeten zijn, en groeit het schema met elk extra formaat. Voor API's waar meerdere representaties een kernvereiste zijn, zoals geo-API's of API's die verifieerbare gegevens uitgeven, is dit een serieuze beperking van het model.

De balans​

Geen van deze zes uitdagingen is een showstopper, en voor elk bestaat een werkbaar patroon. Maar samen tekenen ze een consistent beeld: GraphQL geeft je een krachtig, generiek bevragingsmodel en vraagt in ruil daarvoor dat je conventies die REST van HTTP en van standaarden als de ADR cadeau krijgt, zelf ontwerpt, bouwt en bewaakt. Daarmee is de vraag niet óf GraphQL werkt (dat doet het aantoonbaar, ook op grote schaal), maar wanneer die opgave in verhouding staat tot wat het oplevert. Dat is het onderwerp van deel 4, het slot van deze serie.

In het eerste deel van deze serie maakten we kennis met GraphQL: een getypeerde querytaal waarmee de client exact bepaalt welke data hij ontvangt. Die flexibiliteit is de belangrijkste reden om voor GraphQL te kiezen. In dit deel zetten we eerst de voordelen op een rij en kijken we daarna naar de keerzijde: wat betekent het voor de performance en beschikbaarheid van je API als elke client willekeurige queries kan samenstellen? En vooral: hoe stel je daar grenzen aan?

De voordelen​

Exact de benodigde data, in één roundtrip​

Het voorbeeld uit deel 1 liet het al zien: waar een REST-client soms drie of vier calls nodig heeft en per call te veel of te weinig data ontvangt, haalt een GraphQL-client alles in één request op. Voor toepassingen met veel schermvarianten, trage netwerken of mobiele clients is dat een reëel en meetbaar voordeel.

Autonomie voor clientteams​

Minstens zo belangrijk is het organisatorische effect. In een REST-landschap kan een nieuw scherm een backend-aanpassing vergen: een nieuw of aangepast endpoint en afstemming over de representatie. Met GraphQL stelt het frontend-team zelf een nieuwe query samen op het bestaande schema. Bij organisaties met veel consumerende teams (of externe afnemers met uiteenlopende behoeften) scheelt dat merkbaar in doorlooptijd en afstemming.

Een sterk getypeerd, zelfbeschrijvend contract​

Het schema is een machineleesbaar contract, en daarop bouwt een breed ecosysteem: validatie van elke query tegen het schema, codegeneratie voor clients in vrijwel elke taal, en interactieve verkenning via introspectie.

In het REST-ecosysteem vervult OpenAPI dezelfde rol, met vergelijkbare tooling, en de ADR verplichten zowel een OpenAPI-beschrijving als het publiceren daarvan op /openapi.json. Het verschil zit in de plaats van het contract. Een OpenAPI-document is een apart artefact naast de implementatie: of je het met de hand onderhoudt, uit code genereert of als bron voor codegeneratie gebruikt, synchroon houden blijft een expliciete inspanning. In GraphQL is het schema de runtime zelf. De server weigert elke query die er niet op past en geeft via introspectie precies het schema terug dat hij uitvoert, dus op typeniveau kan het contract niet uit de pas lopen.

Evolueren zonder versies​

REST-API's krijgen bij breaking changes doorgaans een nieuwe major versie. In GraphQL is dat ongebruikelijk: velden worden gemarkeerd met @deprecated en blijven bestaan zolang er clients zijn die ze gebruiken:

type Api {
  titel: String!
  documentatieUrl: String @deprecated(reason: "Gebruik `specificatieUrl`.")
  specificatieUrl: String!
}

Ook OpenAPI kent deprecated: voor operaties en parameters, en via het Schema Object ook voor afzonderlijke velden. Het verschil zit in de feedback. Een REST-response bevat doorgaans de volledige representatie, dus de aanbieder ziet niet of een afnemer een verouderd veld werkelijk gebruikt; uitfaseren gebeurt op basis van aankondigingen en aannames, tenzij de API met sparse fieldsets werkt. Omdat elke GraphQL-client expliciet benoemt welke velden hij opvraagt, is per veld en per afnemer meetbaar wat nog in gebruik is. Dat maakt gerichte uitfasering mogelijk in plaats van een "big bang"-migratie.

Wat overblijft is vooral een verschil in gewoonte: bij REST draait een nieuwe major versie een tijd naast de oude, bij GraphQL groeit één schema additief mee, omdat een tweede versie de hele graph zou dupliceren. Gratis is dat niet, want het schema draagt zijn verleden mee, en definitief verwijderen blijft in beide modellen een breaking change.

De keerzijde: de server verliest voorspelbaarheid​

Bij een REST-API kent de aanbieder elk endpoint en kan die per endpoint redeneren over de kosten: welke database-queries, hoeveel data, welke cache-strategie. Bij GraphQL bestaat "het endpoint" niet meer: elke client stelt zijn eigen bevraging samen. De consequentie: de zwaarte van een request wordt bepaald door de client, niet door de aanbieder.

Het N+1-probleem​

Resolvers werken per veld. Een naïeve implementatie van ons voorbeeldschema:

const resolvers = {
  Query: {
    organisaties: () => db.organisaties.findAll(),
  },
  Organisatie: {
    // wordt aangeroepen voor élke organisatie in het resultaat
    apis: (organisatie) => db.apis.findByOrganisatie(organisatie.id),
  },
};

Een query naar 100 organisaties met hun API's leidt zo tot 1 + 100 database-queries. Hetzelfde patroon geldt voor autorisatie: een toegangscheck die per object wordt uitgevoerd, herhaalt zich in diezelfde query net zo makkelijk honderd keer. Dit N+1-probleem is beheersbaar, bijvoorbeeld met batching via een DataLoader, maar het lost zichzelf niet op en is, zoals hieronder blijkt, ook niet gratis. Zonder maatregelen blijft het vaak onopgemerkt tot er productielast op staat.

Een database die zijn bevragingen niet kent​

Achter het N+1-probleem gaat een structureler vraagstuk schuil. Bij een REST-API is het aantal toegangspatronen eindig: per endpoint schrijf of genereer je de bijbehorende database-queries, ontwerp je de juiste indexen en kun je desnoods een toegesneden read model inrichten. De database wordt, kortom, geoptimaliseerd voor bekende bevragingen.

Bij GraphQL is de bevragingsruimte open. Elke nieuwe query die een clientteam samenstelt, kan een pad door de graph volgen waarvoor geen index of geoptimaliseerde query bestaat; de autonomie die hierboven een voordeel was, is hier de bron van onvoorspelbaarheid. Optimalisatie wordt daarmee reactief in plaats van proactief: je monitort welke operaties traag zijn en bouwt achteraf indexen bij, telkens opnieuw wanneer clients hun queries wijzigen. Ook capaciteitsplanning wordt lastiger, omdat de databasebelasting kan verschuiven met elke client-release, zonder dat er aan de API zelf iets verandert.

Batching via een DataLoader verzacht dit maar gedeeltelijk. Het voorkomt dubbele en herhaalde fetches, maar levert per nestingniveau een aparte WHERE id IN (...)-query op, geen join; de queryplanner van de database kan dus niet doen waar hij goed in is. Frameworks als Hasura en PostGraphile kiezen daarom een andere route en vertalen een GraphQL-query naar één SQL-statement. Dat is efficiënt, maar koppelt het schema aan het framework en vaak ook aan de databasestructuur; op die vorm van coupling komen we in deel 3 terug.

Daar stapelen zich kleinere ongemakken bovenop: efficiënte cursor-paginering vereist passende indexen, en een veld als totalCount kan per opgevraagde pagina een dure count-query betekenen. En ook hier bieden de maatregelen die verderop aan bod komen verlichting: wie kiest voor persisted queries, maakt de set bevragingen weer eindig, en daarmee gericht te optimaliseren.

Geneste queries en het aanvalsoppervlak​

Omdat ons schema circulaire relaties bevat (een organisatie heeft API's, een API heeft een organisatie), is dit een geldige query:

{
  apis {
    organisatie {
      apis {
        organisatie {
          apis {
            organisatie {
              apis { titel }
            }
          }
        }
      }
    }
  }
}

Elke extra nesting vermenigvuldigt het aantal op te halen records. Een paar regels querytekst kan zo miljoenen databaserijen raken. Wat voor een legitieme client een vergissing is, is voor een kwaadwillende een goedkope denial-of-service-aanval: de OWASP GraphQL Cheat Sheet noemt dit als een van de grootste risico's van GraphQL-API's.

Limieten stellen​

Dit terrein is inmiddels volwassen. De gangbare maatregelen, grofweg oplopend in geavanceerdheid:

Depth en amount limiting. Begrens de maximale nesting depth van queries en het maximale aantal op te vragen items per lijst. Eenvoudig te implementeren (vrijwel elke GraphQL-server ondersteunt validatieregels) en een effectieve eerste verdedigingslinie, hier met de library graphql-depth-limit:

const server = new ApolloServer({
  schema,
  validationRules: [depthLimit(6)],
});

Verplichte paginering. Sta geen onbegrensde lijsten toe: geef elk lijstveld een verplicht first-argument met een maximum. Hoe je paginering in het schema modelleert, komt in deel 3 uitgebreid aan bod.

Query cost analysis. Ken elk veld een gewicht toe en bereken vóór uitvoering de totale kosten van een query; boven een drempel wordt de query geweigerd. IBM ontwikkelde hiervoor een draft-specificatie met @cost- en @listSize-directives, waarop onder andere Apollo's Demand Control voortbouwt:

type Query {
  apis(first: Int! = 20): [Api!]! @listSize(slicingArguments: ["first"])
}

type Api {
  gerelateerdeApis: [Api!]! @cost(weight: "5")
}

Rate limiting op kosten in plaats van op requests. Eén GraphQL-request kan het werk van honderd REST-requests doen; een klassieke limiet op "requests per minuut" zegt dus weinig. Ook REST-requests verschillen onderling sterk in kosten; GraphQL maakt dat alleen eerder en explicieter zichtbaar. Shopify beschrijft in detail hoe het afnemers een kostenbudget per tijdseenheid geeft, berekend uit de complexiteit van hun queries; GitHub hanteert een vergelijkbaar puntensysteem voor zijn GraphQL-API.

Persisted queries / trusted documents. De meest vergaande maatregel: sta alleen queries toe die vooraf zijn geregistreerd. Clients sturen niet langer querytekst mee, maar een identifier van een bekend, goedgekeurd document, bijvoorbeeld een SHA-256-hash (de benoemde operaties uit deel 1 lenen zich daar precies voor):

{
  "documentId": "8e2f9b41…",
  "variables": { "id": "min-bzk" }
}

Er loopt een RFC om dit te standaardiseren als onderdeel van de GraphQL over HTTP-specificatie. De observatie die daarbij hoort: wie alleen nog vooraf geregistreerde queries toestaat, heeft de facto weer een eindige set endpoints gecreëerd. Dat is een relativering van de flexibiliteitsbelofte, al blijft het voordeel bestaan dat clientteams die "endpoints" zelf definiëren zonder backend-wijziging.

Operationele basishygiëne. Timeouts op queryniveau, limieten op request-batching, en introspectie uitschakelen (of afschermen) in productie voor API's die niet publiek bedoeld zijn: allemaal terug te vinden in de eerdergenoemde OWASP Cheat Sheet.

Caching: wat HTTP aan REST meegeeft​

Er is nog een tweede keerzijde, en die is minder direct zichtbaar. Een REST-API kan voor caching grotendeels leunen op het web zelf: elke resource heeft een unieke URL, GET-responses zijn met standaard HTTP-headers (Cache-Control, ETag) cachebaar, en elke CDN, proxy of browser kan daarmee overweg, mits de aanbieder die headers correct zet.

GraphQL-verkeer loopt daarentegen vrijwel altijd als POST naar één endpoint. Voor een cache is elk request daarmee uniek en oncachebaar; de documentatie van graphql.org beschrijft dat het URL-mechanisme waarop HTTP-caching leunt, in GraphQL ontbreekt. De gangbare mitigaties:

• GET gebruiken voor query-operaties, met de query in de URL (begrensd door URL-lengtelimieten);
• persisted queries combineren met GET: een korte hash in de URL maakt responses wél CDN-cachebaar;
• caching verplaatsen naar de client (normalized caches zoals die van Apollo Client of Relay) of naar de server (per-veld caching in resolvers).

Waar caching bij REST een eigenschap van het platform is, is het bij GraphQL een bouwopgave. Voor API's die leunen op CDN-caching, zoals veelbevraagde open-data-API's, weegt dit verschil zwaar.

De balans​

De flexibiliteit van GraphQL is geen gratis eigenschap, maar een verschuiving van verantwoordelijkheid: van design-time (de aanbieder ontwerpt endpoints) naar runtime (de aanbieder bewaakt wat clients samenstellen). Wie GraphQL serieus inzet, plant depth limiting, cost analysis, monitoring per operatie en een cachingstrategie daarom in als onderdeel van de basisinrichting, niet als optimalisatie achteraf.

In deel 3 verleggen we de blik van runtime naar design-time: wat komt er kijken bij het ontwerpen van een goed GraphQL-schema, en waarom blijkt dat in de praktijk lastiger dan de voorbeelden doen vermoeden?

Spectral is een open source linter waarmee je regels voor API-documentatie vastlegt in een ruleset en die vervolgens automatisch controleert. Die tool ligt onder vuur. Er staan honderden issues en pull requests open, de VS Code-plugin loopt achter, en half juli kwam daar een supply chain-incident in een van de dependencies bovenop. Dat laatste was voor veel mensen de druppel. Omdat onze eigen tooling op Spectral draait en de API Design Rules ermee beschreven zijn, uitten veel mensen daar terecht hun zorgen over. Ons antwoord: we slopen Spectral er niet halsoverkop uit, want er zit juist beweging in de richting die we toch al op wilden. Hieronder leggen we uit waar we staan en wat we doen.

Wat er is gebeurd​

Op 14 juli werden twee kwaadaardige versies van @asyncapi/specs naar npm gepubliceerd, via een gecompromitteerde branch in de repository van AsyncAPI. De latest-tag wees korte tijd naar de besmette versie. De payload startte bij het inladen van de package een achtergrondproces dat een remote access tool downloadde, die vervolgens onder meer opgeslagen browserwachtwoorden, SSH-keys, GITHUB_TOKEN, NPM_TOKEN en AWS-credentials wegsluisde. De details staan in issue 656 van asyncapi/spec-json-schemas.

Waarom dat ons raakt: @stoplight/spectral-rulesets heeft @asyncapi/specs als dependency, met een caret-range. Wie in dat tijdvenster een schone install deed van Spectral, haalde de besmette versie binnen. Onze eigen tooling gebruikt Spectral onder de motorkap en de API Design Rules zijn met een Spectral ruleset beschreven.

Eerst het goede nieuws. De aanval was niet gericht op Spectral en Stoplight is hier net zo goed slachtoffer als iedereen verderop in de keten. De kwaadaardige versies werden snel door npm en Github verwijderd waardoor latest weer naar de laatste schone versie verwees. Een verse install van vandaag is veilig.

De druppel, niet het begin​

Het incident zelf is dus opgelost. De reactie erop niet. Op de Spectral-repository is op 14 juli een issue geopend met de melding dat Spectral gecompromitteerde dependencies binnenhaalde, en dat issue staat er twee weken later nog steeds, onbeantwoord, terwijl er in de tussentijd wel een release is gedaan. Bij een supply chain-incident is de snelheid waarmee een maintainer reageert belangrijker dan de vraag of het incident zijn schuld was.

Dat past in een beeld dat al langer zichtbaar is. Kin Lane, die al jaren als de API Evangelist over dit vakgebied schrijft, onderbouwt het met cijfers in de blogpost waarin hij bekendmaakt dat hij Spectral heeft geforkt: 241 openstaande issues, een terugval van 93 procent in het aantal gesloten issues ten opzichte van de piek in 2021, en een oudste openstaande pull request van vijf jaar geleden. Daar komt bij dat de VS Code-plugin al ruim een jaar niet is bijgewerkt, en dat er install-time telemetrie in zit die weliswaar netjes gedocumenteerd is en uit te zetten, maar die je in een overheids-CI liever bewust dan per ongeluk aan hebt staan.

Wij lopen daar zelf ook tegenaan. Een goed voorbeeld is de or-functie in de ADR-ruleset, waarover in november een vraag binnenkwam. Die ruleset gebruikt function: or, en dat is een ingebouwde functie die in april 2025 aan Spectral is toegevoegd. De CLI kent hem en doet netjes wat er staat. De VS Code-plugin draait op een Spectral-build van daarvoor en meldt dat de functie niet bestaat. Dezelfde ruleset, dezelfde API, twee verschillende uitkomsten. De melder was een paar uur kwijt aan het zoeken naar een fout die niet in zijn API zat en ook niet in de ADR.

Het probleem is dus niet de regel. Het probleem is dat nergens is vastgelegd welke functies bij welke versie van het rulesetformaat horen. Het formaat heeft geen eigen versienummer: het is in de praktijk "wat de linter die je toevallig draait accepteert". Voor één tool valt daarmee te leven. Voor een standaard op de pas-toe-of-leg-uit-lijst, die door tientallen organisaties in verschillende omgevingen wordt gedraaid, niet.

Er zit beweging in​

Dit is niet nieuw voor ons en we zijn er ook niet gisteren pas over gaan nadenken. We hebben hier de afgelopen tijd meerdere gesprekken over gevoerd met Kin en anderen in het veld, en wisten dus al dat er beweging aan zat te komen. Wat er nu gebeurt maakt vooral zichtbaar wat er al langer speelde.

De kern van het betoog: Spectral is eigenlijk twee dingen in één. Het is een specificatie voor hoe je regels over JSON- en YAML-documenten uitdrukt, en het is een tool die die regels evalueert. Die twee zijn nooit gescheiden. Het regelformaat leeft in de broncode van de linter en wordt mee geversioneerd met die tool. Als de tool stilvalt, valt het formaat ook stil. En je regels zijn het duurzame deel, niet de linter die ze toevallig uitvoert.

Kin's fork onder API Commons splitst die twee alsnog, in twee repositories:

• Het rulesetformaat als zelfstandige specificatie, met één portable JSON Schema (draft 2020-12) in plaats van vijf interne draft-07 meta-schema's die aan de runtime van de linter hangen.
• De linter zelf als onderhouden build van v6.16.2, met volledige commithistorie, zonder telemetrie, en met issues die openstaan voor reactie.

Hoe een en ander uiteindelijk gaat heten staat nog open, dus verwacht daar de komende tijd nog wijzigingen.

Het formaat blijft gelijk en bestaande rulesets blijven werken. Het verschil zit in het onderhoud: verbeteringen die nu blijven liggen kunnen er wel worden opgepakt en uitgebracht. Precies daar liep het bij or op vast.

Waarom niet gewoon vacuum?​

De meest gestelde vervolgvraag was waarom we niet overstappen op vacuum. Dat is een goede tool en op dit moment beter onderhouden dan Spectral. Toch is het voor ons op dit moment nog geen vervanging, om drie redenen:

• Ten eerste is de compatibiliteit met het Spectral-rulesetformaat niet volledig. Dat formaat is precies wat wij willen behouden: de ADR zijn ermee beschreven, en dat geldt ook voor de rulesets die we voor OAS-, publiccode.yml- en JSON-FG-validatie hebben geschreven.

• Ten tweede is vacuum, hoe goed ook, in de praktijk een eenmansproject. Dan verplaatsen we het probleem alleen maar: we stappen weg bij een tool waar te weinig mensen naar omkijken, en komen uit bij een tool die van één persoon afhangt.

• Ten derde is vacuum geschreven in Go. Onze tooling moet ook in de browser en in editors kunnen draaien, en dat wordt met een gecompileerde binary al snel ingewikkeld. Een JavaScript-engine heeft dus onze sterke voorkeur. Dat Spectral trager is dan vacuum weegt daar niet tegenop: de codebase van Spectral is jarenlang organisch gegroeid en er valt nog genoeg aan te sleutelen voordat de taal de beperkende factor wordt.

Wat we gaan doen​

Spectral blijft voorlopig in gebruik. We updaten versies in onze tooling niet zomaar en niet automatisch. Een update is bij ons een bewuste keuze, geen bijproduct van een build. Dat lost het onderliggende onderhoudsprobleem niet op, maar het haalt de acute onzekerheid eruit: een linter die je in CI draait op een versie die je zelf hebt vastgesteld, tegen specificaties die je zelf beheert, is een beheersbaar risico. Dit incident had iedereen kunnen raken die zijn afhankelijkheden automatisch laat meebewegen, dus het is sowieso een goed moment om te kijken hoe dat bij jou geregeld is.

We gaan bijdragen aan het nieuwe project. Het probleem dat Kin beschrijft, hebben we samen met hem doorgenomen. Dat is ook precies waarom we het niet bij toekijken laten: we helpen mee waar we kunnen, aan zowel de specificatie als de linter. En we nodigen iedereen die met dit formaat werkt uit om hetzelfde te doen. Hoe meer partijen meedoen, hoe minder dit afhangt van de goede wil van één leverancier of één persoon.

We helpen zoeken naar een plek om te landen. Een fork is nog geen standaard. De OpenAPI Initiative is een optie, al gaat Spectral verder dan OpenAPI alleen en sluiten de statuten van de OAI tooling expliciet uit, wat lastig is als het er juist om gaat de specificatie en de tool bij elkaar te houden. De Linux Foundation is een optie. En een Europese publieke-sectorplek is dat ook: een aanzienlijk deel van de meest geavanceerde toepassing van dit formaat zit bij Europese overheidsprogramma's, en verschillende van die landen voeren nu hetzelfde gesprek. Wij denken daarin mee.

Waar wij geen voorstander van zijn, is Spectral er halsoverkop uitslopen. Dat zou betekenen dat de ADR herschreven moet worden in een formaat dat we niet in de hand hebben, op basis van een incident dat inmiddels is ogelost, terwijl er juist beweging zit in de richting die wij toejuichen.

Wat je zelf kunt doen​

Werk je met de ADR, gebruik dan de DON Checker in plaats van Spectral rechtstreeks. Hoe je hem draait voor ADR staat beschreven op de pagina over de ADR Checker in onze kennisbank. Deze tool draait via CLI of in de browser, en wij houden de onderliggende linter en de rulesets bij. Je verplaatst je afhankelijkheid daarmee naar een Nederlandse overheidsorganisatie, waarvan je mag verwachten dat we open zijn en blijven. Mis je een regel, klopt er iets niet of loop je ergens tegenaan, meld het dan gerust in de issues van die repository.

Gebruik je zelf het Spectral-rulesetformaat, laat dat dan even weten in de discussion bij API Commons. Het maakt zichtbaar wie er meekijkt, en dat is precies wat er tot nu toe ontbrak in elk gesprek over waar dit formaat thuishoort.

Heb je vragen over wat dit betekent voor je eigen implementatie van de ADR of voor je gebruik van onze validatietooling, neem dan contact op via developer.overheid@geonovum.nl.

In gesprekken over API's binnen de overheid komt GraphQL regelmatig voorbij. Sommige organisaties experimenteren ermee, grote internationale platformen zoals GitHub en Shopify bieden er publieke API's mee aan, en tegelijkertijd is het binnen de Nederlandse overheid nog nauwelijks zichtbaar: het API-register op deze site is bewust REST-only, en de REST API Design Rules (ADR) zijn, de naam zegt het al, geschreven voor REST.

Reden genoeg om GraphQL eens grondig onder de loep te nemen. In een serie van vier blogposts verkennen we wat GraphQL is, wat het oplost, welke uitdagingen het met zich meebrengt en, als kernvraag, wanneer je het wel en wanneer je het beter niet kunt gebruiken.

Wat is GraphQL?​

GraphQL is een querytaal voor API's, gecombineerd met een schemataal om een sterk getypeerd datamodel te beschrijven en een runtime die queries tegen dat model uitvoert. Het is in 2012 ontwikkeld bij Facebook, dat worstelde met de datavoorziening van zijn mobiele apps, en in 2015 open source gemaakt. Sinds eind 2018 wordt de specificatie beheerd door de onafhankelijke GraphQL Foundation, onderdeel van de Linux Foundation. In september 2025 verscheen de September 2025 Edition, de eerste nieuwe editie sinds oktober 2021.

De bouwstenen​

Het schema​

Het hart van elke GraphQL-API is het schema, geschreven in de Schema Definition Language (SDL). Het schema beschrijft welke types er bestaan, hoe ze samenhangen en welke queries mogelijk zijn. Een sterk vereenvoudigd voorbeeld, losjes gebaseerd op het API-register:

type Organisatie {
  id: ID!
  naam: String!
  apis: [Api!]!
}

type Api {
  id: ID!
  titel: String!
  versie: String!
  organisatie: Organisatie!
}

type Query {
  organisatie(id: ID!): Organisatie
  organisaties: [Organisatie!]!
  apis: [Api!]!
}

Het uitroepteken markeert verplichte (non-nullable) velden. Let op de relaties: een Organisatie heeft apis, en een Api verwijst terug naar zijn organisatie. Het schema vormt zo een graph van samenhangende types; vandaar de naam.

Queries​

De client stelt een query samen die qua vorm het gewenste antwoord spiegelt:

{
  organisatie(id: "min-bzk") {
    naam
    apis {
      titel
      versie
    }
  }
}

De server antwoordt met exact de gevraagde velden, niets meer en niets minder:

{
  "data": {
    "organisatie": {
      "naam": "Ministerie van BZK",
      "apis": [
        { "titel": "Adressenregister API", "versie": "2.1.0" },
        { "titel": "Organisaties API", "versie": "1.0.3" }
      ]
    }
  }
}

Variabelen​

In de praktijk schrijven clients geen letterlijke waarden in de query, maar benoemde operaties met variabelen:

query ApisVanOrganisatie($id: ID!) {
  organisatie(id: $id) {
    naam
    apis {
      titel
    }
  }
}

{ "id": "min-bzk" }

De query wordt daarmee een herbruikbaar, valideerbaar document dat los van de invoer bestaat. Onthoud deze vorm: in deel 2 zien we dat zulke benoemde documenten de basis vormen voor beheersmaatregelen zoals persisted queries.

Mutations en subscriptions​

Schrijfoperaties heten mutations. Ze zijn in het schema expliciet gescheiden van queries en geven, net als queries, precies de gevraagde velden terug:

mutation {
  registreerApi(
    input: { titel: "Vergunningen API", organisatieId: "gm0363" }
  ) {
    id
    titel
  }
}

Daarnaast kent GraphQL subscriptions: de server pusht wijzigingen naar de client zodra die zich voordoen, een patroon dat aansluit bij Event Driven Architecture. In de rest van deze serie richten we ons op het bevragen van data; het ontwerp van mutations en subscriptions laten we verder buiten beschouwing.

Resolvers​

Aan de serverkant wordt elk veld ingevuld door een resolver: een functie die weet hoe de waarde van dat ene veld opgehaald moet worden. Hoe de data achter de schermen is opgeslagen (één database, meerdere services, een externe API) is voor de client onzichtbaar. Dat maakt GraphQL ook geschikt als orkestratielaag: een schema dat gegevens uit meerdere bestaande API's combineert en in samenhang bevraagbaar maakt, zonder die bronnen te vervangen. Op dat patroon komen we in deel 4 terug.

Introspectie​

Een GraphQL-API is zelfbeschrijvend: via een standaard introspectie-query kan elke client het volledige schema opvragen. Daarop bouwt een rijk ecosysteem van tooling, zoals interactieve explorers (GraphiQL), automatische documentatie en codegeneratie voor clients.

Dezelfde vraag in REST​

Hoe zou de bovenstaande informatiebehoefte er met een klassieke REST-API uitzien? Waarschijnlijk ongeveer zo:

GET /organisaties/min-bzk
GET /organisaties/min-bzk/apis

De eerste call levert de volledige organisatie-representatie op, inclusief adresgegevens, contactinformatie en andere velden die we in dit scenario niet nodig hebben. Dat heet overfetching. Levert de tweede call alleen samenvattingen op, dan is per API mogelijk nog een extra call nodig voor de details: underfetching, met meerdere roundtrips tot gevolg.

Dit is het probleem waarvoor GraphQL is ontworpen. In één request, in één roundtrip, precies de benodigde data, ongeacht hoeveel types de vraag raakt. Voor Facebook, met trage mobiele netwerken en een nieuws-feed vol diep geneste, onderling verbonden data, was dat de bestaansreden.

REST kan hetzelfde bereiken, met zorgvuldig ontworpen resources, fields- of expand-parameters, of een specifiek op een scherm toegesneden endpoint. Het verschil is dat GraphQL deze flexibiliteit generiek biedt, terwijl je haar in REST per geval ontwerpt. Op die afweging komen we in deel 2 uitgebreid terug.

Een ander paradigma, geen "betere REST"​

Het is verleidelijk GraphQL te zien als "REST, maar dan handiger". Dat doet beide tekort. Het verschil wordt zichtbaar zodra je naar het HTTP-verkeer kijkt. Een minimale variant van de benoemde operatie uit de paragraaf over variabelen gaat zo over de lijn:

POST /graphql HTTP/1.1
Content-Type: application/json

{
  "query": "query Naam($id: ID!) { organisatie(id: $id) { naam } }",
  "variables": { "id": "min-bzk" }
}

Eén endpoint, vrijwel altijd POST, en de eigenlijke vraag zit in de body. Voor het netwerk is elk GraphQL-request identiek; wat er gevraagd wordt, is alleen zichtbaar voor wie de body parseert. Zet de twee modellen naast elkaar:

• REST modelleert resources en leunt op de semantiek van HTTP: werkwoorden (GET, POST, PUT, DELETE), statuscodes, unieke URI's per resource, cache-headers en content negotiation. Het netwerk "begrijpt" een REST-API: een cache, proxy of loadbalancer kan zinvol reageren op wat er langskomt.
• GraphQL modelleert een graph van types en gebruikt HTTP vooral als transport. Vrijwel al het verkeer gaat via één endpoint (meestal POST /graphql), antwoorden komen doorgaans terug met status 200 OK, ook als er iets misging, en fouten staan als data in de responsebody.

In onze eerdere blogpost over OpenAPI 3.1 constateerden we dit al: GraphQL gebruikt HTTP wel als protocol, maar volgt niet het HTTP-model waarop specificaties als OpenAPI zijn gebaseerd. De GraphQL over HTTP-specificatie, die vastlegt hoe GraphQL-verkeer over HTTP hoort te lopen, is op het moment van schrijven (medio 2026) nog een working draft; het transportgedrag ligt formeel dus nog niet vast.

Dit paradigmaverschil is de rode draad van deze serie. Vrijwel elk voordeel én vrijwel elke uitdaging van GraphQL is erop terug te voeren: wat je wint aan flexibiliteit in de bevraging, moet je elders opnieuw organiseren. Denk aan caching, autorisatie en beheersing van de belasting.

De rest van deze serie​

In de komende delen gaan we de diepte in:

• Deel 2 behandelt de kernbelofte van GraphQL (flexibel bevragen als oplossing voor over- en underfetching) en de prijs die daar tegenover staat: onvoorspelbare performance en een groter aanvalsoppervlak, en hoe je daar limieten aan stelt.
• Deel 3 duikt in de praktijk van schema-ontwerp: paginering, filtering, union types, custom scalars, autorisatie en content negotiation.
• Deel 4 brengt alles samen in een afwegingskader: wanneer is GraphQL een logische keuze, en wanneer ben je met REST beter af, zeker binnen de context van de Nederlandse overheid en de ADR.

Een compacte referentie over GraphQL, met de status binnen de overheid en de belangrijkste specificaties, staat in de kennisbank.

Een goede API begint niet bij de controller, maar bij het contract. In de Bouw een API-tutorial laten we zien hoe je vanuit een gevalideerde OpenAPI Specification servercode genereert. Tot nu toe lag de nadruk daar vooral op een Express-template als demonstratie. Inmiddels hebben we de template-repository uitgebreid met meer runtimes en programmeertalen.

Dat klinkt misschien als een kleine toolingstap, maar het raakt een praktisch probleem dat veel teams herkennen: hoe kom je van een nette OAS naar een applicatie die dezelfde afspraken ook echt afdwingt?

Dit artikel zoomt bewust in op één concrete stap: codegeneratie na het ontwerpen en valideren van je API-contract. Niet de hele toolingketen, maar de vraag wat er gebeurt zodra je OAS klaar is en je team met implementeren wil beginnen. Voor de bredere gedachte achter generators, validators en agents verwijzen we naar Tools in the loop.

Waarom templates?​

OpenAPI Generator kan code genereren voor tientallen talen en frameworks. Dat is handig, maar de standaard output is generiek. Voor een API bij de Nederlandse overheid wil je juist dat de gegenereerde applicatie aansluit op de manier waarop we API's ontwerpen:

• de OpenAPI-specificatie is het contract;
• request-validatie gebeurt op basis van dat contract;
• foutmeldingen gebruiken application/problem+json;
• de gegenereerde code heeft duidelijke plekken voor businesslogica;
• de oorspronkelijke OAS blijft gepubliceerd bij de applicatie;
• de output is geschikt als startpunt voor implementatie, niet als losstaande eindoplossing.

Daarvoor gebruiken we de codegen-templates repository. Die bevat aangepaste templates bovenop OpenAPI Generator. Je gebruikt dus nog steeds de bekende generator, maar met projecttemplates die beter passen bij de design-first workflow op developer.overheid.nl.

Wat kun je ermee?​

De basisflow is hetzelfde als in de tutorial:

1. Maak of onderhoud je OpenAPI-specificatie.
2. Valideer die specificatie met de DON Checker of ADR-ruleset.
3. Bundel externe $refs, zodat de generator een zelfstandig bestand krijgt.
4. Genereer een applicatie met een template.
5. Implementeer de businesslogica op de daarvoor bedoelde plekken.

Bijvoorbeeld:

npx @redocly/cli bundle ./openapi.json \
  --output openapi.bundled.json \
  --ext json

npx @developer-overheid-nl/don-checker@latest validate \
  --ruleset adr-21 \
  --input openapi.bundled.json

git clone https://github.com/developer-overheid-nl/codegen-templates.git

Daarna kies je de runtime die past bij je team of applicatie.

Beschikbare templates​

Op dit moment bevat de repository templates voor:

De Node.js- en NestJS-templates zijn het meest uitgewerkt. De Go-, Java-, Rust- en Python-templates zijn toegevoegd als basisvarianten en moeten nog verder in echte API-applicaties worden beproefd.

Wat levert de gegenereerde code op?​

De templates genereren geen complete productieapplicatie. Ze geven je een startpunt waarin het saaie en foutgevoelige werk al is gedaan.

Denk aan:

• routes die overeenkomen met de paden uit je OAS;
• modellen/types op basis van de schemas;
• request-validatie voor parameters en bodies;
• controllers, services, delegates, traits of base classes waar je eigen code aan koppelt;
• standaardresponses voor ontbrekende implementaties;
• publicatie van het broncontract of runtime OpenAPI-document, bijvoorbeeld via /openapi.yaml of /openapi.json.

De belangrijkste winst zit in de scheiding tussen contract en implementatie. De OAS bepaalt welke operatie bestaat, welke parameters geldig zijn en welke schemas over de lijn gaan. De gegenereerde code volgt dat contract. Je team kan zich daarna richten op de domeinlogica: databases, autorisatie, integraties, logging, monitoring en testen.

Een voorbeeld: NestJS of FastAPI​

Voor een NestJS-app ziet genereren er bijvoorbeeld zo uit:

npx @openapitools/openapi-generator-cli generate \
  -i openapi.bundled.json \
  -g typescript-nestjs-server \
  -o ./generated-api-nestjs \
  -t ./codegen-templates/nestjs-fastify \
  -c ./codegen-templates/nestjs-fastify/generator-config.yaml \
  --skip-validate-spec \
  --additional-properties=npmName=generated-api-nestjs,npmVersion=1.0.0,nestVersion=11.0.0,rxjsVersion=7.8.2,tsVersion=5.9.3,nodeVersion=22.0.0

De template maakt abstracte API classes en controllers. Je koppelt je eigen implementaties via de gegenereerde module. Ontbreekt een implementatie, dan krijg je standaard een 501 application/problem+json response. Dat is handig in de ontwikkeling: je ziet direct welke operatie nog geen echte invulling heeft.

Voor Python/FastAPI is het patroon vergelijkbaar:

npx @openapitools/openapi-generator-cli generate \
  -i openapi.bundled.json \
  -g python-fastapi \
  -o ./generated-api-python \
  -t ./codegen-templates/python-fastapi-template \
  -c ./codegen-templates/python-fastapi-template/generator-config.yaml \
  --additional-properties=packageName=generated_api_python,packageVersion=1.0.0,serverPort=1337

FastAPI en Pydantic verzorgen de request-validatie. De template zet validatiefouten om naar 400 application/problem+json en maakt per API-groep base classes waar je implementatie van kan erven.

Waarom is dit handig?​

Codegeneratie wordt soms gezien als iets dat vooral boilerplate bespaart. Dat doet het ook, maar voor API-ontwikkeling is het belangrijker dat het de werkwijze expliciet maakt.

Als je eerst code schrijft en daarna documentatie genereert, ontstaat er snel discussie over wat leidend is. Is de controller de waarheid? De documentatie? Een test? Een wiki? Bij design-first is de OAS de afspraak. De templates helpen om die afspraak niet alleen te publiceren, maar ook te gebruiken in de applicatie zelf.

Dat heeft een paar voordelen:

• reviewers kunnen eerst het contract beoordelen voordat er implementatiedetails bijkomen;
• frontend- en backendteams kunnen eerder parallel werken;
• mockservers en gegenereerde stubs maken testen eerder mogelijk;
• afwijkingen van de API Design Rules worden eerder gevonden;
• teams kunnen in verschillende talen werken zonder de API-werkwijze telkens opnieuw uit te vinden.

Voor overheidsorganisaties is dat extra relevant. API's worden vaak door andere organisaties gebruikt, soms jaren nadat het oorspronkelijke team alweer veranderd is. Een duidelijk contract en voorspelbare foutafhandeling maken zo'n API beter beheerbaar.

Geen magie, wel een betere start​

De templates nemen niet alles over. Je moet nog steeds nadenken over security, autorisatie, logging, performance, datamodellering en beheer. Je moet ook de gegenereerde code testen in je eigen stack. Zeker de nieuwere templates vragen nog praktijkervaring en bijdragen uit projecten.

Maar ze verlagen wel de drempel om goed te beginnen. In plaats van een leeg frameworkproject krijg je een applicatie die al weet welke operaties bestaan, welke input geldig is en waar je de implementatie moet plaatsen.

Meedoen​

De templates zijn open source. Gebruik ze, probeer ze uit op een bestaande OAS en open vooral issues of pull requests als je iets mist of verbetert.

"Human in the loop" is inmiddels het standaardantwoord op bijna elke zorg rond AI. Maar voor wie AI inzet om overheidssoftware te bouwen, is het verstandig om naast de mens ook tools in de loop houden: generators die het zware werk doen en validators die de regels bewaken. Zo verschuift het naleven van standaarden van de oplettendheid van een mens en de welwillendheid van AI naar tooling die je kunt vertrouwen. Hoe dat samenwerkt, en aan welk arsenaal aan skills, generators, validators en andere tools we werken, lees je in deze post.

Validators en generators worden steeds belangrijker​

Je zou kunnen denken dat in een wereld waarin een AI-agent "gewoon de code schrijft" de behoefte aan generators en validators afneemt. Het tegenovergestelde is waar. Juist omdat een taalmodel plausibel-ogend werk produceert dat tóch fout kan zijn, wordt het werk dat je níet aan het model wilt overlaten belangrijker dan ooit.

Dat werk bestaat uit twee soorten. Het zware, repetitieve werk, zoals het genereren van boilerplates en het opzetten van een projectstructuur, dat kun je een generator laten doen. Die is deterministisch en doet elke keer hetzelfde. En de waarheidsvraag, "Voldoet dit aan de regels die wij hanteren?", kun je door een validator laten beantwoorden. Niet AI, niet de mens, maar een tool met een vaste set regels.

Bovendien hoeft AI zo minder zelf te "bedenken". Dat scheelt hallucinaties en het verbrandt geen onnodige tokens. Het model doet waar het goed in is, namelijk taal en intentie interpreteren, en de tools doen waar zij goed in zijn.

CLI als natuurlijke interface voor AI-agents​

Agents leven op de command line. Ze roepen tools aan, lezen de output, en bepalen op basis daarvan hun volgende stap. Dat maakt een CLI de meest natuurlijke interface die je een agent kunt aanbieden: deterministisch, scriptbaar, aan elkaar te knopen, en met een exit code en gestructureerde output waar een agent direct op kan itereren.

Daarom hebben onze tools sinds kort allemaal een command line interface gekregen, van de generators tot de checkers. Een invalid output uit onze checker is daarmee een exit status: de agent leest het, ziet wat er mis is, past het aan en draait de checker opnieuw. Daar draait de hele validatieloop op, zonder dat er een mens tussen hoeft te zitten.

Hoe alles samenwerkt​

Vanuit developer.overheid.nl bieden we de volgende features (deels al, deels binnenkort) aan. De rolverdeling:

• Schema Register. Een register van herbruikbare JSON schema's waar straks niet alleen mensen, maar ook agents uit kunnen putten. In plaats van schema's te verzinnen, verwijst de agent naar wat er al is. Met de komende upgrade naar OpenAPI 3.1 zijn deze schema's direct te gebruiken in OAS-documenten. Dit register is momenteel in ontwikkeling; we verwachten dit snel te kunnen lanceren.
• Agent Skills. Hiermee geven we agents instructies mee: welke tool, op welk moment, in welke volgorde. De skill is wat de agent dwingt om onze tooling te gebruiken in plaats van zelf te improviseren. Deze zijn in beta en nog volop in onderzoek, dus gebruiken op eigen risico! Eerder schreven we al over hoe je standaarden in je AI-assistant laadt.
• OAS Generator. Genereert een boilerplate OpenAPI-document op basis van een input.json. Die boilerplate is al ADR-conform van opzet, dus de agent begint niet van scratch maar met een correct startpunt.
• Checker. Onze linter/validator die een document toetst aan een ruleset, bijvoorbeeld de ADR-ruleset voor een OAS of de publiccode-ruleset voor publiccode.yml. Bij valid mag de pijplijn door, bij invalid moet er opnieuw geïtereerd worden. Dit is de spil waar de hele kwaliteitsborging om draait.
• Codegen Templates. Eigen OpenAPI Generator templates, zodat de gegenereerde servercode voor API's aansluit op de API Design Rules en andere overheidsstandaarden. Momenteel hebben we een aantal smaken in de aanbieding, waaronder voor Java, Go, Node.js, Rust en Python.
• Repo Docs Generator. Genereert de standaard repo-documentatie: een README.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, LICENSE, SECURITY.md, CHANGELOG.md en een publiccode.yml. In één keer nette, consistente templates in plaats van handmatig samengeraapte bestanden.

De AI doet in dit geheel maar twee dingen: de input.json vullen, een vast formaat dat het model kent, en via dialoog met de gebruiker die input compleet maken. Pas als de input volledig is, wordt er daadwerkelijk gegenereerd.

Generator en checker zijn complementair​

Een terechte vraag is: als de generator al een boilerplate maakt conform de API Design Rules (ADR), en de agent borduurt voort op wat er al staat, heb je die checker dan überhaupt nog nodig?

Het antwoord is ja, en het waarom is meteen het sterkste argument vóór deze opzet. Het klopt dat een agent geneigd is om voort te borduren op een bestaand, intern consistent document. Een schone boilerplate werkt als voorbeeld: de agent ziet hoe wij naar het register verwijzen, hoe we fouten modelleren, welke naming we hanteren, en trekt dat door. Dat is precies waarom je met een goede boilerplate begint. Het vernauwt de output, scheelt tokens en verkleint de kans op afwijkingen.

Maar het is geen garantie. Naarmate een document groeit, valt de oorspronkelijke boilerplate buiten het effectieve aandachtsvenster van het model. Voeg je functionaliteit toe waar geen voorbeeld voor in het document staat, dan valt het model terug op zijn trainingsdata, en die is niet ADR-conform. En over meerdere bewerkingen heen kunnen kleine afwijkingen zich opstapelen.

Daarom zijn de generator en de checker geen overlap maar complementair. De generator-boilerplate zorgt dat de checker bijna altijd meteen valid teruggeeft. De checker is er voor de keren dat dat niet zo is, of als er na de generatie nog wijzigingen aan de OAS doorgevoerd worden. Denk aan extra endpoints, filters, etc. De checker handhaaft de harde grens die een taalmodel statistisch nooit kan garanderen.

Een overheids-API bouwen​

Tijd om te laten zien hoe die loop er in de praktijk uitziet. De onderstaande flowchart toont het hele proces in één oogopslag; daaronder lopen we de stappen langs.

De gebruiker geeft de prompt "bouw een overheids-API". De juiste skill wordt getriggerd en stuurt de agent door een vast proces. Eerst verzamelt de agent input: deels door vragen te stellen aan de gebruiker, deels door het schema-register te doorzoeken naar bruikbare, herbruikbare schema's. Het resultaat is een complete input.json.

Die input gaat de OAS Generator in, die er een boilerplate openapi.json van maakt. Vervolgens komt de Checker om de hoek kijken. Deze toetst het document tegen de ADR-ruleset. Is het invalid, dan gaat het terug: de agent fixt de OAS en draait de checker opnieuw, net zo lang tot het klopt. Óók als het document na de generatie nog gewijzigd wordt dus.

Het belangrijkste aan dit plaatje is de lus rond de checker. De agent kan niet langs de regels. Hij mag itereren, hij mag fouten maken, maar hij komt pas verder als een deterministische tool groen licht geeft. De waarheid zit niet in het model, maar in de checker.

De code open source maken​

Precies hetzelfde patroon keert terug voor een ander prompt. De flowchart hieronder laat zien hoe:

"Maak dit open source" trapt een vergelijkbaar proces af: de juiste skill wordt getriggerd, de agent verzamelt input en laat dat door de Repo Docs Generator lopen. Die genereert in één keer de complete set repo-documentatie, van README.md en CONTRIBUTING.md tot CODE_OF_CONDUCT.md, LICENSE.md, SECURITY.md, CHANGELOG.md en een publiccode.yml. Vervolgens komt dezelfde checker terug, nu met de publiccode-ruleset, die de publiccode.yml toetst. Is het invalid, dan fixt de agent het bestand en draait de checker opnieuw, exact dezelfde lus als bij het bouwen van de API. Saillant detail: als er reeds een README.md is, zoals het geval is nadat je de OpenAPI-generator hebt gebruikt, zal de agent deze aanpassen conform de template van de generator, welke de best practices voor een README.md bevat.

In het geval van een bestaande codebase, instrueert de skill de agent om te kijken naar de git remote, bestanden als openapi.json en het projectmanifest (zoals een package.json, pyproject.toml of pom.xml) om daar de benodigde input uit te halen. Doe je dit prompt vanuit de bestaande context, dan weet de agent nog dingen uit de eerdere input. Denk hierbij bijvoorbeeld aan de contactgegevens uit de zojuist gegenereerde OAS.

Standaarden​

Er zit een randvoorwaarde onder dit hele verhaal, en die verdient het om expliciet genoemd te worden: standaarden. De templates, generators en validators uit deze blog bestaan alleen omdat er standaarden onder liggen waar we ze tegenaan kunnen bouwen, de ADR, de publiccode-standaard, herbruikbare schema's. Zonder een vaste set regels is er niets om een boilerplate op te baseren of een document tegenaan te toetsen.

Hoe meer er gestandaardiseerd wordt, hoe nauwkeuriger we onze templates, generators en validators kunnen maken. Elke afspraak die we vastleggen is een stukje waarheid dat we uit het model kunnen halen en in deterministische tooling kunnen stoppen. Standaardisatie is de fundering die betrouwbaar bouwen met AI mogelijk maakt. Hoe steviger die fundering, hoe meer je met een gerust hart aan de tools kunt overlaten.

Conclusie​

Het resultaat is een proces dat reproduceerbaar en controleerbaar is. Dezelfde input levert dezelfde output, en wat eruit komt voldoet aantoonbaar aan onze regels, niet omdat een model toevallig goed gemutst was of een reviewer scherp oplette, maar omdat een tool het heeft afgedwongen.

De rolverdeling is daarmee helder. Het taalmodel is de orkestrator die intentie vertaalt naar input en tools aanroept, niet het orakel dat de waarheid bepaalt. Generators doen het zware werk, validators bewaken de grenzen. En de mens blijft gewoon in de loop, maar op het niveau waar menselijk oordeel telt: keuzes, context, akkoord. Niet op het naleven van regels die een machine beter onthoudt.

Of je AI inzet is aan jou. Maar áls je het doet, houd dan niet alleen de mens in de loop, maar óók beschikbare tools.

Een inmense uitdaging, met een duidelijke eerste stap​

De dag werd geopend met een stevige bezetting vanuit verschillende ministeries, een voor een kwamen de uitdaging waar wij als land voor aan de lat staan naar voren. De groei van AI, en de uitwerking daarvan. De Cloud strategie, Digitale souvereiniteit, en veiligheid. Allemaal vragen waar het antwoord elke keer eenduidig was: Samen. Samen werken, samen doen en samen ontwikkelen. Dit werd ook beaamt door de `vreemde aap' in het gezelschap. Gedragswetenschapper Patrick van Veen welke het gedrag van door hem onderzochte apen als spiegel voor de aanwezigen hield om hen zo te laten zien wat 'samen werken' precies kan betekenen.

Druk bezochte talks, lege gangen.​

Een van de dingen die opviel (in tegenstelling tot andere grotere events) is dat de wandelgangen en koffiehoekjes volstrekt uitgestorven waren tijdens de talks. De verschillende stands op het Kennisplein werden dan wel goed bezocht tijdens de pauzes, maar tijdens de talks was het vooral aan de standhouders zelf om onderling een gesprek aan te gaan. Een positief iets, als je het mij vraagt.

kennisplein​

Het kennisplein fungeert als vraagbaak en ook sociale lijm tussen de talks door. Met 'standhouders' zoals Open source werken, developer.overheid.nl en ook Forum Standarisatie was het voor geinspireerde luisteraars een peulenschil om bijpassende expertise te vinden en vragen en discussies voort te zetten. Robot-hond Adam, tot leven gewekt op een lokaal draaiend LLM trok bekijks, en natuurlijk ook de nodige technische interesse. Hoe werkt zo'n Lokaal LLM dan?, maar ook andere onderwerpen zoals de open source werkplek werden al snel onderwerp van langdurige gesprekken tussen potentieele toekomstige gebruikers.

Vervolg​

Ben jij CIO binnen de (bredere overheid) of vervul je een aanpalende rol, dan is de volgende CIO dag wellicht ook iets voor jou. Deel ervaringen met collega's, stel jou meest prangende vragen, of raak geinsprireerd door de vele sprekers. We moeten het tenslotte samen met elkaar oplossen.

CloudEvents​

Waar AsyncAPI zich richt op het beschrijven van berichtenstromen, biedt het niet een gestandaardiseerde manier om events zelf vorm te geven. Het documenteert wel wat er voor berichten over de lijn gaan, maar het definieert geen uniforme set metadata, zoals type, bron, identificatie of tijdstip, die losstaat van de inhoud van het bericht. Daarmee ontstaat een scheiding tussen wat een event is en wat een event bevat. Deze scheiding onderkennen is één ding, hem goed kunnen beschrijven is een tweede, en dit is waar CloudEvents om de hoek komt kijken.

In een eerdere blogpost is al uitgebreid over CloudEvents gesproken in de context van Event-Driven Architecture. Zie al wat volgt dan ook vooral als een vervolg op de AsyncAPI mention die daar kort in voorkomt, en als een manier om de zaken uit de vorige twee posts in deze reeks van een theoretische realisatie te voorzien.

Laat ik dan ook teruggrijpen naar een eerdere observatie: AsyncAPI maakt expliciet wat er over de lijn gaat, maar laat veel ruimte in hoe dat er concreet uitziet. Die flexibiliteit is krachtig en tevens deel van wat de specificatie zo aantrekkelijk maakt, maar kan ook leiden tot variatie waar je die misschien niet wil hebben. Twee teams kunnen hetzelfde soort event modelleren, maar toch verschillende keuzes maken in metadata, naamgeving of contextinformatie. Binnen één team of tussen twee nauw-verbonden teams is dat vaak nog te overzien, maar op grotere schaal zal dit geheid uitlopen op problemen.

CloudEvents vangt precies dat probleem af door een minimale, duidelijke standaard neer te zetten voor event-metadata en het beschrijven/definiëren van het event zelf. Opgenomen als NL GOV profiel en door Forum Standaardisatie op de “pas toe, leg uit” lijst gezet, CloudEvents specifieert onder andere uniforme naamgeving en metadata, afspraken over payloads en headers, notificatie toepassingen van de overheid en meer. Dit is precies wat AsyncAPI open laat. Door CloudEvents als standaard te combineren met AsyncAPI ontstaat een gelaagd model: AsyncAPI beschrijft de structuur, het gedrag en de context van berichtenstromen, terwijl CloudEvents zorgt voor een consistente “envelop” waarin die berichten worden verstuurd. Het resultaat is een combinatie waarin zowel documentatie als implementatie beter op elkaar aansluiten.

Toepasgebied​

Wanneer zou dit nou echt tot zijn recht komen? Los van alle use-cases die in eerdere posts besproken zijn kijk ik hier vooral naar situaties waarin interoperabiliteit een belangrijke rol speelt. Binnen de Nederlandse overheid is het koppelen met systemen van andere organisaties, of zelfs andere teams en omgevingen binnen de eigen organisatie aan de orde van de dag. Systemen van verschillende organisaties moeten met elkaar communiceren, vaak zonder dat er sprake is van directe afstemming of gezamenlijke ontwikkeling. Teams binnen grote landelijke organisaties lopen er ook tegenaan dat ze afhankelijk zijn van de events die de wereld in gaan vanuit teams waar ze nooit direct mee in aanraking komen. In zulke omgevingen is het niet voldoende dat iedereen “ongeveer hetzelfde” doet; consistentie en voorspelbaarheid zijn randvoorwaarden voor een goede dienstverlening.

Notificaties​

Een concreet voorbeeld hiervan is het uitwisselen van notificaties tussen ketenpartners. Wanneer een gebeurtenis plaatsvindt, bijvoorbeeld een wijziging in een registratie of de afronding van een processtap, kan die informatie relevant zijn voor meerdere afnemers. Denk aan de notificatie dat er iets in de kadastrale gegevens van een huizenblok gewijzigd gaat worden. Door zo’n gebeurtenis als CloudEvent te versturen, voorzien van gestandaardiseerde metadata en opgesteld volgens een NLgov standaard wordt het voor afnemers eenvoudiger om events te routeren, filteren en verwerken. Ontwikkelaars en architecten hoeven niet te wachten of te gissen naar hoe events eruit zien en wat voor soorten gegevens erin komen te staan; ze kunnen het gewoon opzoeken en afvangen. AsyncAPI kan in deze context gebruikt worden om vast te leggen welke events bestaan, hoe de payload eruitziet en welke semantiek eraan verbonden is. Daarmee heb je de combinatie te pakken van “wat is er allemaal” en “hoe ziet het eruit”; oftewel, vorm en inhoud van de communicatie worden hiermee helder.

Cross-team integraties​

Een ander scenario waarin deze combinatie waarde toevoegt, is dat van cross-team en cross-organisatie integraties. Denk aan het moment dat een team van de Politie een event van een ander team binnen de Politie wil afnemen, of dat een team bij de KMar datzelfde event ook ergens voor nodig heeft. Zoals eerder beschreven ontstaat daar vaak een situatie waarin overzicht op de volledige keten makkelijk te verliezen is, met als gevolg dat er meerdere waarheden gaan ontstaan. Door CloudEvents te gebruiken als gemeenschappelijke basis voor event-metadata, kunnen teams onafhankelijk van elkaar werken zonder dat ze telkens opnieuw afspraken moeten maken over basiselementen zoals identificatie of herkomst. AsyncAPI fungeert daarbij als de plek waar die events formeel worden beschreven en gedeeld. Dit ondersteunt het idee van een “single source of truth”, zonder dat het de autonomie van individuele teams beperkt.

Auditing en replay​

Ook in meer technische use cases, zoals auditing of event replay, biedt de combinatie duidelijke voordelen. CloudEvents schrijft bijvoorbeeld voor dat elk event een unieke identifier en timestamp bevat. Dat lijkt een detail, maar maakt het aanzienlijk eenvoudiger om events later opnieuw te verwerken of te analyseren. Voor organisaties die willen voldoen aan de transparantie principes die ten grondslag liggen aan zaken als Wet Open Overheid is het goed na kunnen gaan en aan kunnen tonen wat er met data gebeurt, wie wat initieert en waar gegevens naartoe gaan van cruciaal belang. In combinatie met het relatief makkelijke versiebeheer in AsyncAPI ontstaat zo een robuuste basis voor het omgaan met historische data, zelfs wanneer schema’s in de loop der tijd veranderen. Kortom, in het kader van auditing en transparantie is dit alles zeker geen overbodige luxe binnen een complex bolwerk als de gehele Nederlandse overheid.

Hoe dit aan te pakken?​

De vraag is dan hoe een implementatie van deze combinatie er in de praktijk uit zou gaan zien. In de basis begint het met het vaststellen van een aantal afspraken op organisatieniveau. AsyncAPI alleen bleek al baat te hebben bij duidelijke keuzes rondom naamgeving, perspectief en tooling; met CloudEvents komt daar een extra laag bij. Denk aan afspraken over welke attributen verplicht zijn, hoe typen worden benoemd en hoe bronnen worden geïdentificeerd. Zonder die afspraken bestaat het risico dat de standaard wel wordt gebruikt, maar niet op een consistente manier. Hier is voor CloudEvents al een NLgov profiel voor opgesteld en verplicht gesteld (“pas toe, leg uit”). AsyncAPI heeft deze nog niet, omdat de discussie over het toepassingsgebied nog een lopende zaak is, maar laten we er t.b.v. het uitdenken van een implementatie er even vanuit gaan dat een dergelijke duiding wel komt.

Na het opstellen van afspraken en/of “leg uit’s” in de context van “pas toe, leg uit” komt de modellering zelf. In AsyncAPI wordt vastgelegd welke events bestaan, via welke Channels ze worden uitgewisseld en hoe de payload is opgebouwd. Dit is een inhoudelijke klus die kennis van AsyncAPI vereist, maar ook kennis van de daadwerkelijk te modelleren berichtenstroom. CloudEvents kan daarin op verschillende manieren worden geïntegreerd, bijvoorbeeld door het als basis te nemen voor de message-structuur of door expliciet te verwijzen naar de CloudEvents-specificatie binnen de schema’s. Het belangrijkste is dat duidelijk wordt gemaakt waar de grens ligt tussen generieke metadata en domeinspecifieke inhoud.

Dan de technische implementatie. Voor producers betekent dit dat zij verantwoordelijk zijn voor het correct opbouwen van CloudEvents, inclusief de verplichte metadata. De exacte manier van implementatie is sterk afhankelijk van de organisatie, maar in de kern zullen er techneuten aan de slag moeten gaan met het opstellen van CloudEvents die aansluiten op wat er op hoger niveau is afgesproken. Tegelijkertijd zullen eventuele consumers hun applicaties moeten inrichten op de AsyncAPI documentatie en informatie over de CloudEvents van de producer, in het vertrouwen dat dergelijke metadata altijd aanwezig en consistent is. Middleware, zoals messaging-platforms of event brokers, kan vervolgens gebruikmaken van die metadata voor routering, filtering of logging, zonder dat kennis van de payload nodig is. Een voordeel hiervan is dat het bijdraagt aan verdere ontkoppeling, omdat infrastructuur en businesslogica minder van elkaar afhankelijk worden.

Wat de opvallende lezer vast allang heeft gemerkt is dat hier eigenlijk geen nieuwe concepten worden geïntroduceerd, maar dat er slechts bestaande patronen explicieter en consistenter worden gemaakt. Veel systemen gebruiken immers al vormen van metadata in hun berichten; CloudEvents neemt de rol aan om daar structuur in aan te brengen, en AsyncAPI pakt de rol op om de berichtenstromen zichtbaar, beheersbaar en overdraagbaar te maken. Juist die combinatie van standaardisatie en documentatie maakt het mogelijk om event-driven werken op grotere schaal toe te passen zonder dat het verzandt in maatwerkafspraken.

Kijkje naar de toekomst​

Dit is, in een notendop, hoe een implementatie van CloudEvents met AsyncAPI eruit zou kunnen zien. Het is natuurlijk een kijk naar de toekomst, en daardoor zijn concrete voorbeelden binnen de Nederlandse overheid nog niet voorhanden. We zijn echter niet de enigen die de link tussen deze twee gezien heeft; binnen AsyncAPI is vanaf het begin al waarde gezien in het combineren van CloudEvents en AsyncAPI.

De kaders die in eerdere posts geschetst zijn blijven overigens in dit alles van toepassing. In kleine, gesloten systemen zal de meerwaarde beperkt zijn, en kan de extra complexiteit moeilijk te rechtvaardigen zijn. In grotere, dynamische en organisatie-overstijgende omgevingen ligt dat anders. Daar kan de combinatie van AsyncAPI en CloudEvents een belangrijke rol spelen in het realiseren van consistente, betrouwbare en toekomstbestendige communicatie. Daarmee vormt het een logische volgende stap voor organisaties die niet alleen hun asynchrone communicatie willen beschrijven, maar deze ook daadwerkelijk willen standaardiseren en operationaliseren binnen een bredere event-driven architectuur.

Met deze reeks aan blogposts heb ik geprobeerd een kijkje te geven in de keuken van de werkgroep AsyncAPI, en ook vast wat vooruit te lopen op de zaken die daar nu spelen. Mocht je na dit alles gelezen te hebben denken “dit klinkt interessant”, “oh maar daar heb ik een interessante use case voor”, of misschien iets als “maar dat weet ik veel beter”, schroom dan vooral niet om je aan te melden voor de werkgroep via api@geonovum.nl!

Anne Schuth: Platform engineering​

Anne Schuth opende met een prikkelende stelling: de Nederlandse overheid is misschien wel het grootste softwarebedrijf van Nederland, waarom organiseert ze zich dan nog niet zo? Hij liet zien hoe platform engineering developers kan ontlasten, hoe je standaarden by design kunt afdwingen en hoe beleid letterlijk onderdeel kan worden van je code, inclusief verwijzingen naar wetsartikelen.

Anne Schuth tijdens zijn talk over platform engineering.

Dimitri en Tom: features live demo​

Onze collega’s Dimitri van Hees en Tom Ootes lieten aan de hand van een live demo zien welke verbeteringen aan onze producten er allemaal zijn doorgevoerd. Dimitri liet zien hoe je een API bouwt met behulp van de AI-Skills van developer.overheid.nl en de OAS-generator tool die direct voldoet aan de API Design Rules. In de tweede fase van de demo maakte Tom de repository klaar voor open source gebruik. Hij deed dit met behulp van een bijbehorende AI-Skill en de repo-docs-generator tool.

Foto van het koffiemoment.

Johan Groenen: code.overheid.nl​

Johan Groenen nam ons mee in code.overheid.nl: de nieuwe gedeelde gitomgeving voor de overheid, gebouwd op Forgejo. Niet alleen een alternatief voor GitHub, maar vooral een plek waar overheidsdevelopers samen kunnen werken aan open source software, een stap richting digitale soevereiniteit.

Johan Groenen tijdens zijn talk over code.overheid.nl.

Jan Klopper: OpenKAT​

Jan Klopper liet zien wat OpenKAT mogelijk maakt: een open source securitytool, ontstaan bij VWS tijdens de coronacrisis en inmiddels gedragen door een actieve community. Met slimme plugins, de zogenoemde boefjes, breng je het aanvalsoppervlak van je organisatie feitelijk en forensisch geborgd in kaart.

Jan Klopper tijdens zijn praatje over OpenKAT.

Vervolg​

Wil je zelf aan de slag? Er volgen workshops waarin we dieper ingaan op de tools, standaarden en toepassingen die tijdens de middag voorbij kwamen. Houd hiervoor onze website in de gaten.

Zet in je agenda​

Belangrijk nieuws: de datum voor de volgende editie is ook al bekend. Dat zal namelijk 15 december zijn. Noteer hem in je agenda en houd opensourcewerken.nl in de gaten, daar zal het event tzt verschijnen.

Verder willen we graag alle sprekers en developers bedanken voor hun bijdragen, vragen en ideeën. Tot de volgende keer!

Op 9 en 10 juni stonden wij twee dagen op FOST Amsterdam met onze eigen NL Gov-track. FOST (Future of Software Technologies) begon ooit als de wereldbekende API Days-conferentie, maar groeide uit tot een wereldwijd paraplu-event waaronder verschillende miniconferenties vallen; oprichter Mehdi Medjaoui maakte gekscherend de vergelijking van monoliet naar microservices. Naast API Days zelf vallen daar onder meer de conferenties van OpenAPI, JSON Schema, AsyncAPI, Green IO en deze editie dus ook wijzelf onder. Ons goedbezochte event bestond uit twee onderdelen: een API-track en een open source-track. Van ons eigen developer.overheid.nl-team betraden Dimitri, Tom, Frank, Floris en Joost het podium, samen met andere collega's uit binnen- en buitenland. Een terugblik op twee inspirerende dagen.

API-track​

Nationale API-strategie en governance​

Hoe bouw je een nationale API-strategie, en hoe krijg je organisaties mee zonder ze te dwingen? Die vraag liep als een rode draad door meerdere talks.

Dimitri van Hees blikte terug op acht jaar developer.overheid.nl. Het ontstond tijdens een bijeenkomst van de Europese Commissie in Italië, bedoeld om API-kennis tussen lidstaten uit te wisselen. Hier was Nederland het enige land dat met meer dan één organisatie aanwezig was; zowel Kadaster, CBS, BZK en de gemeente Amsterdam waren onafhankelijk van elkaar uitgenodigd om, bij gebrek aan een centrale IT-organisatie, de Nederlandse digitale overheid te vertegenwoordigen. Op diezelfde bijeenkomst ontmoetten ze Roberto Polli, wiens team toen al ver was met een eigen developer portal; developer.overheid.nl is mede op dat voorbeeld gebaseerd. Wat begon als een simpele lijst van overheids-API's, is inmiddels een kennisbank voor zowel consumenten als aanbieders. Omdat een formeel mandaat ontbreekt, werkt het platform via waarde toevoegen: vindbaarheid, gratis validatietools en beveiligingsscans. Het API-register accepteert alleen API's met een OpenAPI-specificatie, kent scores toe op basis van de API Design Rules en ondersteunt lifecyclemanagement. Recent toegevoegd: een Open Source Register op basis van publiccode.yml, notificaties via RSS en Slack, en experimenten met AI Agent Skills.

Roberto Polli, voorheen van het Dipartimento per la Trasformazione Digitale, was mede-verantwoordelijk voor de totstandkoming van de Italiaanse developer portal en API-strategie, precies het register dat Dimitri als inspiratie noemde. In een van zijn twee talks liet hij zien hoe die strategie tot stand kwam. Het oude SOAP-framework werkte prima voor grote instanties, maar met opstartkosten van zo'n 200.000 euro was het onbetaalbaar voor de meer dan 8.000 kleine gemeenten. De overstap naar een REST-vriendelijk framework was dus een kwestie van toegankelijkheid. De lockdown van 2020 maakte de urgentie zichtbaar, en daarna volgde een API Cloud waarin instanties verplicht hun API's publiceren en handmatige overeenkomsten zijn vervangen door digitale delegatie. Zijn vier randvoorwaarden voor succes: politiek commitment, technische expertise in de uitvoering, betrokkenheid bij internationale standaardisatie, en juristen die in het team zitten in plaats van op een aparte afdeling.

Roberto Polli sprak over de Italiaanse API-strategie.

Frank Terpstra, die al jaren aan de Nederlandse API-strategie werkt, ging in een panel in gesprek met Dimitri en Janette Storm (Kadaster). Daar kwam het spanningsveld scherp naar voren: je moet een standaard eerst laten werken voordat je die verplicht stelt. Een "wall of shame" werkt averechts, want wie niet voldoet laat zich liever van de lijst halen dan zich aanpassen. Ook bleek dat je per doelgroep een andere taal moet spreken: beleidsmakers zoeken kostenbesparing, productmanagers willen klantcontact verbeteren en developers kijken naar concrete Design Rules en tooling. Mooie observatie: API's worden steeds vaker ingezet om het datakopieerprobleem bespreekbaar te maken bij bestuurders, een thema dat de krantenkoppen haalt. Tot slot klonk de roep om meer Europese coördinatie.

Tim van der Lippe (Logius) presenteerde de NLgov REST API Design Rules. Elke regel is gebaseerd op echte beslissingen van overheidsorganisaties waarvan inmiddels bekend is of ze goed of slecht uitpakten. Door de standaard, het API-register en analyses van API's in het wild samen te brengen, ontstaat een levende standaard die gevoed wordt door wat developers daadwerkelijk bouwen.

Schemas en semantische interoperabiliteit​

Verschillende organisaties beschrijven dezelfde entiteit vaak op totaal verschillende manieren. Vier sprekers lieten zien hoe je daar met schemas en semantiek grip op krijgt. Over dit thema verschijnt binnenkort een aparte en uitgebreidere blogpost.

Tom Collins werkt voor de DVLA, de Britse instantie voor rijbewijzen en voertuigen, en beheert gegevens over zo'n vijftig miljoen voertuigen. Zijn oplossing voor teams die in silo's dezelfde begrippen anders definiëren, is het Schema Dictionary: een centraal Git-repository op basis van JSON Schema. De werkwijze is schema-first, het datamodel wordt via peer-reviews beoordeeld voordat er code is, en vanuit de centrale schema's worden automatisch code, documentatie, OpenAPI-contracten en testdata gegenereerd. Inmiddels gebruiken zo'n 450 repositories het systeem; bij het medische rijbewijsverlengingsproces, dat zes productteams overspant, steeg het percentage klanten dat het volledig digitaal kon doorlopen van 15 naar 100 procent. Ook hier gold "carrot rather than the stick". De aanpak is bewust puur structureel: de standaardisatie zit in de schema's zelf, zonder semantische laag eroverheen.

Dimitri constateerde dat overheids-API's veel meer delen dan ze hergebruiken. Geïnspireerd door het Schema Dictionary van de DVLA bouwt developer.overheid.nl daarom zelf aan een nationaal schema-register dat herbruikbare OpenAPI-componenten en JSON Schemas beschikbaar stelt als bouwstenen, met bijbehorende schema-ontwerpregels. Hij liet ook zien hoe zijn team eigen tooling en AI-hulpmiddelen inzet om een complete OpenAPI 3.1-specificatie met ingebedde JSON Schemas te genereren en valideren.

Ingo Simonis (Open Geospatial Consortium) draaide het perspectief om: niet de hoeveelheid data telt, maar de betekenis ervan. Een AI-agent faalt niet omdat hij data niet kan bereiken, maar omdat hij die niet betrouwbaar kan interpreteren. Niet-gedeclareerde eenheden, lokale categorieën en impliciete referentiesystemen zijn stuk voor stuk uitnodigingen om te raden, en raden op de semantische laag is waar hallucinaties ontstaan. Zijn stelling: organisaties die de AI-decade winnen, behandelen expliciete kennis als infrastructuur, niet als documentatie. De semantische gemeenschap lost dit probleem al dertig jaar op, merkte hij droog op, en de rest van de wereld arriveert nu pas aan de deur.

Ingo Simonis betoogde dat semantiek, niet de hoeveelheid data, bepaalt of AI-agents informatie betrouwbaar interpreteren.

Op precies die drempel stond de andere talk van Roberto Polli. JSON-LD bestaat allang; de echte brug zit in iets kleiners. Door een extensie als x-jsonld-context toe te voegen aan een OpenAPI-document leg je de link tussen een schema en zijn betekenis direct in de specificatie, en stapt de schema-first wereld door de deur die Ingo schetste. Elke data-eigenschap krijgt een URI die de exacte betekenis vastlegt, zodat Italiaanse data automatisch koppelt aan bijvoorbeeld Finse of Nederlandse standaarden zonder dat de onderliggende systemen veranderen. In Italië is dit al verplicht voor de publieke sector, ondersteund door centrale tools als api.gov.it (meer dan 12.000 publieke API's) en schema.gov.it (met een real-time conformiteitscore). De boodschap: maak van de standaard een shortcut, dan omarmen developers die vanzelf. Inmiddels hebben wij vanuit Nederland vervolggesprekken ingepland met onze Italiaanse en Britse collega's, het OGC en de Stelselcatalogus, om dit gezamenlijk aan te pakken.

Events en notificaties​

Met de verschuiving naar Event-Driven Architecture groeit de behoefte aan standaarden voor ontkoppelde berichtstromen. Twee talks gingen hierop in, beide voortgekomen uit werkgroepen van het Kennisplatform API's.

Floris Deutekom presenteerde de stand van zaken van de AsyncAPI-werkgroep. AsyncAPI bouwt voort op OAS, is protocol-agnostisch (Kafka, RabbitMQ, HTTP en meer) en levert out-of-the-box tooling voor validatie, documentatie en codegeneratie. In twee praktijkgevallen, de Basisregistratie Ondergrond en Track & Trace van het Ministerie van Justitie, bleken conversietools betrouwbaarder en sneller dan handmatig werk. AsyncAPI heeft vooral meerwaarde bij ontkoppelde architecturen, een onbekend aantal consumenten of een-op-veel-communicatie, en de combinatie met CloudEvents biedt een uniform kader. Floris is over AsyncAPI een serie blogposts aan het schrijven, en de eerste staat al online.

Floris Deutekom presenteerde de stand van zaken van de AsyncAPI-werkgroep.

Danny Greefhorst (BZK/ICTU) plaatste notificaties in de context van een dataspace voor de Nederlandse overheid, waarin dataproviders en consumenten rechtstreeks met elkaar interacteren op basis van rulebooks, met data bij de bron als kernprincipe. De voorkeur gaat uit naar informatie-arme notificaties die naar de bron verwijzen, wat beveiliging en dataminimalisatie bevordert. Van de drie patronen, polling, directe notificatie en een event broker, is voor de Nederlandse overheid met potentieel 1.600 organisaties alleen de broker schaalbaar genoeg. CloudEvents vormt de standaard voor de metadata, inclusief een Nederlands profiel. De grootste uitdaging ligt overigens niet in de techniek, maar in de organisatorische bereidheid om events daadwerkelijk te delen.

Updates uit andere werkgroepen​

Naast AsyncAPI en notificaties deelden ook andere werkgroepen van het Kennisplatform API's hun voortgang.

Joost Farla trekt de nieuwe werkgroep Historie, die zich richt op het omgaan met bitemporaliteit in API's bij de overgang van Nederlandse registraties van EBMS en StUF naar moderne REST API's. De meeste API's kennen alleen de staat van nu, terwijl de werkgroep twee tijdlijnen onderzoekt: geldigheidstijd (wanneer was iets waar in de werkelijkheid) en transactietijd (wanneer is het vastgelegd). Zo wordt een vraag mogelijk als: wat was de weersverwachting voor zaterdag, zoals we die gisteren kenden? De werkgroep verkent oplossingsrichtingen als append-only in plaats van overschrijven, opvragen op tijdcoördinaten met parameters als validAt en recordedAt, en idempotentie via idempotency keys. Er speelt ook een spanning met de AVG, want append-only botst met het recht om vergeten te worden; een verkende oplossing is crypto-shredding, waarbij niet de data maar de encryptiesleutel wordt vernietigd. De kernboodschap: historie is een functionele eis, geen bijproduct. Over dit onderwerp volgt binnenkort een aparte en uitgebreidere blogpost.

Joost Farla sprak namens de nieuwe werkgroep Historie over bitemporaliteit in API's.

Frank gaf daarnaast een update vanuit de werkgroep rond access control. Binnen de publieke sector bestaan best practices voor toegangscontrole bij API's, en de huidige best practice, de module access control van de API Design Rules, is door de werkgroep herzien. Frank lichtte toe wat er is veranderd en kondigde aan dat er een publieke consultatie van start gaat. Wie meer wil weten of wil meedenken, kan via die consultatie bijdragen.

API's in de praktijk​

Drie talks lieten zien hoe overheids-API's op grote schaal in de praktijk werken.

Janette Storm (Kadaster) liet zien hoe de Basisregistratie Adressen en Gebouwen (BAG), een van de meest gebruikte dataregistraties van de Nederlandse overheid, meegroeide met de API-wereld. Vóór 2009 had elke gemeente een eigen adresregistratie, sindsdien is er één centrale registratie waarvan gemeenten het onderhoud blijven doen. De eerste BAG API verscheen in 2019 bijna per toeval, uit een proof-of-concept met linked data, en won meteen de Gouden API-award. Opvallend was het adoptieprofiel: private partijen als TomTom en Esri stapten snel over, terwijl overheden langer vasthielden aan XML. De slimste zet was het oplossen van de puzzel voor de gebruiker: in plaats van losse objecten die je zelf moet samenvoegen, biedt een kant-en-klaar adreseindpunt nu 90 procent van het gebruik. Binnenkort volgt een overstap naar de PDOK Locatie API met betere ondersteuning voor historische data.

Die overstap sluit aan bij het verhaal van John Schaap (Kadaster) over PDOK (Publieke Dienstverlening Op de Kaart), het nationale geodataplatform met meer dan 200 datasets, bijna 300 API's en diensten en miljoenen requests per dag. De uitdaging: complexe, heterogene geo-data toegankelijk én bruikbaar maken voor moderne applicaties. Data ontsluiten is niet genoeg; developers hebben snelle, consistente en intuïtieve API's nodig. John deelde de ontwerpprincipes achter PDOK's OGC API's en de PDOK Locatie API, waarmee PDOK evolueerde van traditionele geoservices naar een modern API-ecosysteem met vector tile-visualisatie en slimme zoekmogelijkheden.

Bart Huijbers (Kadaster) opende ten slotte de motorkap van het Digitaal Stelsel Omgevingswet (DSO). Sinds 1 januari 2024 voegt de Omgevingswet tientallen wetten rond ruimtelijke ordening, milieu, natuur en water samen, en het DSO is de ICT-ruggengraat daaronder, van publicatie van regelgeving tot vergunningchecks en vergunningaanvragen. Naar buiten toe is het één portaal, onder de motorkap een samenspel van componenten die via een reeks API's data uitwisselen. Aan de hand van concrete use cases liet Bart zien hoe die API's werken en welke afwegingen daarin zijn gemaakt.

Open source-track​

De open source-track stipte uiteenlopende thema's aan, van digitale autonomie en wetgeving tot publiccode.yml en digitale democratie.

Digitale autonomie begint bij open source​

Tom Ootes opende de open source-track plenair met een duidelijke boodschap: digitale autonomie begint bij open source. Een week voor FOST presenteerde Europa het Tech Sovereignty Package (3 juni 2026), met onder andere de Cloud and AI Development Act, Chips Act 2.0 en een nieuwe Europese Open Source Strategie. Centraal staat het begrip digitale commons: code en infrastructuur die collectief geproduceerd worden, vrij toegankelijk zijn en in het publiek belang onderhouden worden, terwijl Europees open source-werk nu nog onevenredig wordt uitgebuit door grote niet-Europese techbedrijven. Voor de Nederlandse overheid betekent dat technische volwassenheid: zelf open source kunnen bouwen, hosten en onderhouden, met platform-engineering als cultuur en samenwerking als norm via gedeelde design-systems, code.overheid.nl en gedeelde Kubernetes-clusters. Over AI was Tom scherp: LLM's en agentic AI helpen ons sneller coderen, maar vibe-coding voor productie keurt hij ten zeerste af en de ethische kant moet nog worden opgelost. Het goede nieuws: de urgentie en politieke steun zijn er, OSPO's schieten op binnen de overheid en developers staan te popelen.

Tom Ootes opende de open source-track plenair.

Soevereine infrastructuur en wetgeving​

Marlena van Ooijen (Logius) begon met een tegenstelling: sinds 2020 werkt het Ministerie van Binnenlandse Zaken aan open source-beleid, maar in de praktijk gebeurt overheidsontwikkeling nog grotendeels op GitHub. Steeds meer organisaties delen de overtuiging dat échte open source-samenwerking een gedeelde, soevereine omgeving vereist. Het antwoord is code.overheid.nl, een overheidsbrede git-forge op basis van Forgejo, nog in de pilotfase, waarvan de roadmap samen met de gebruikers wordt uitgewerkt.

August Bournique nam ons mee in de Cyber Resilience Act, de Europese wet die productveiligheid voor digitale producten, software inbegrepen, reguleert en in 2026 en 2027 gefaseerd in werking treedt. Hij gaf een kijkje achter de schermen bij het ontwikkelen van de eerste productgerichte softwarestandaarden voor de CRA. De wet is ambitieus en de implementatie nog onzeker; August lichtte de tijdlijn toe, en stond stil bij openstaande vraagstukken. Een grote misconceptie die August graag uit de lucht wilde halen was dat open source-contributers ook verantwoordelijk kunnen gehouden voor productie-implementaties van hun software, dit is uitdrukkelijk niet zo.

August Bournique sprak over de Cyber Resilience Act.

publiccode.yml als standaard​

Waar Dimitri eerder inzoomde op het API-register, koos Tom voor de open source-catalogus, die begin dit jaar volledig publiccode.yml-first is geworden en inmiddels meer dan 4.000 repositories van de hele Nederlandse overheid telt. publiccode.yml is een metadatastandaard uit 2018, actief onderhouden door developers.italia.it en de Europese Commissie. Het is een vlag die je in je repository plant zodat je project vindbaar wordt, gitforge-agnostisch en laagdrempelig, met catalogi in Frankrijk, Italië, Duitsland en Nederland. Maar de standaard schiet nog tekort: hij is ontworpen voor grote, monolithische applicaties, terwijl het landschap nu draait op REST API's, cross-organisationele data-uitwisseling en kleinere componenten. Tom riep op om publiccode.yml toe te voegen aan je repositories, een catalogus op te zetten en issues in te dienen. Dat is makkelijker geworden, want het team heeft een AI-skill uitgebracht die het bestand voor je genereert.

Valerio Como (Developer Italia) sloot hier mooi op aan met zijn werk aan de Public Code Editor, die de Italiaanse overheid gebruikt zodat ook niet-technische mensen eenvoudig een publiccode.yml kunnen maken. De uitdagingen waren herkenbaar: onboarding van nieuwe bijdragers, technische schuld wegwerken, betrouwbaarder releasen en het ontwikkelproces opschalen.

Frank Terpstra en Valerio Como, die de Public Code Editor van Developer Italia toelichtte.

Digitale democratie​

Twee talks gingen over open source-platformen voor digitale democratie.

Consul Democracy, toegelicht door Lucía Luzuriaga, ondersteunt participatieprocessen als consultaties, participatief begroten en gezamenlijk beleid maken, en wordt wereldwijd door overheden ingezet. Open source maakt transparantie mogelijk, maar brengt ook uitdagingen mee rond het onderhouden van bijdragen, governance en technische duurzaamheid. Lucía benadrukte waarom een sterke, internationale civic tech-community onmisbaar is.

Raoul Kramer vertelde het verhaal achter Polis, een open source participatieplatform dat gelijktijdige digitale discussies tussen duizenden mensen mogelijk maakt, met stellingen als vertrekpunt. Zijn talk ging over de weg naar een bruikbare tool: welke ontwerpkeuzes zijn nodig om Polis geschikt te maken voor de Nederlandse overheid? Aan het einde deelde hij het blijde nieuws dat Polis onder een nieuwe internationale samenwerking verdergaat: Voxit.

Open source-beheer in de praktijk​

Tot slot bracht Thomas Steenbergen (OSSYN) zijn OSS Review Toolkit (ORT) voor het voetlicht. Het opzetten van open source-beheerprocessen is complex, met tientallen programmeertalen, build-tools en afleveringsmethoden, en commerciële tools sluiten zelden goed aan op wat Open Source Program Offices nodig hebben. Meerdere OSPO's bouwden daarom samen ORT. Thomas demonstreerde hoe het een volledige FOSS-review doorloopt: van het scannen van broncode op componenten, licenties en kwetsbaarheden, via het oplossen van issues, tot het genereren van attributiedocumenten en CycloneDX- en SPDX-SBOMs. Wie FOSS-beleid wil automatiseren via Policy as Code en reviewtijd wil besparen, heeft er een kant-en-klare oplossing aan.

Tot slot​

Twee dagen FOST leverden een rijk palet aan inzichten op, van nationale strategieën en schemas tot digitale autonomie en democratie. Wat ons betreft was de rode draad helder: standaarden werken het best als ze het makkelijker maken om het goed te doen dan om het fout te doen. We kijken terug op een geslaagde editie en danken alle sprekers. Houd onze blog in de gaten voor de aangekondigde, uitgebreidere posts over schemas en bitemporaliteit!

Toegevoegde waarde van AsyncAPI​

Daar horen een paar disclaimers bij. Bovenal moet duidelijk zijn dat dit gaat om een work-in-progress; de discussie over welke use cases passend zijn voor het gebruik van AsyncAPI is in volle gang. Zie dit dan ook echt als een voorlopige observatie, en niet als een definitieve aanbeveling. Daarnaast wil ik ook echt nogmaals iets benoemen dat in de eerdere post ook gedeeld is: niet elke asynchrone interactie vraagt om een uitgebreide specificatie, en niet elk systeem wordt beter van extra documentatie en tooling. In plaats van een harde scheiding op basis van techniek lijkt het nu meer dat het onderscheid gemaakt wordt door de complexiteit van het landschap, de mate van ontkoppeling en de dynamiek van verandering. Met die algemene punten gezegd hebbende, laten we gaan kijken naar hoe de splitsing er op dit moment uit lijkt te zien, te beginnen met de “happy flow”, de gevallen waarin AsyncAPI aan de orde is en echt iets toevoegt.

Onbekende afnemers​

Een van de meest kenmerkende situaties waarin dit het geval is, is die waarin je niet (meer) precies weet wie je afnemers zijn. In traditionele, synchrone API’s is dat doorgaans helder: een client roept een endpoint aan en verwacht een antwoord. Die relatie is expliciet en vaak ook beheersbaar. In asynchrone omgevingen vervaagt dat beeld. Een systeem publiceert een event, maar heeft geen volledig zicht op wie dat event consumeert, laat staan wat ermee gebeurt. Juist daar helpt AsyncAPI om een contract neer te zetten dat losstaat van individuele afnemers. Niet door te beschrijven wie er luistert, maar door vast te leggen wat er over de lijn gaat en onder welke voorwaarden. Dat lijkt een subtiel verschil, maar maakt in de praktijk het onderscheid tussen impliciete afhankelijkheden en expliciete afspraken.

1-op-N communicatie​

Die dynamiek wordt nog duidelijker in situaties waarin communicatie niet langer één-op-één is, maar één-op-veel. In OpenAPI wordt in dergelijke gevallen al snel vereist dat je dit op basis van webhooks oplost, of dat je een grote hoeveelheid endpoints gaat modelleren (en elke keer weer nieuwe bij moet definiëren als er iets wijzigt). Er zijn zeker gevallen waarin dit prima is of zelfs de voorkeur heeft (zie verderop), maar het neemt niet weg dat wanneer de situatie opschaalt AsyncAPI native ondersteuning biedt voor “1 event -> multiple consumers”; je hoeft niks te forceren, het is ervoor gemaakt. Een enkel event kan door meerdere systemen worden opgepakt, ieder met een eigen interpretatie en vervolgactie. Door die gebeurtenis centraal te beschrijven, ontstaat er een gedeeld referentiepunt zonder dat je de onderlinge relaties hoeft dicht te timmeren. Het gevolg is een vorm van ontkoppeling die niet alleen technisch, maar ook organisatorisch ruimte biedt.

Ontkoppelde request-response flows​

Een derde categorie waarin AsyncAPI zich nadrukkelijk bewijst, is die waarin timing geen vaste rol speelt. Dit is in wezen de primaire use-case waar AsyncAPI voor is opgetuigd, namelijk een asynchrone flow. In een request-response model zit er per definitie een directe relatie tussen vraag en antwoord; de één wacht op de ander. In asynchrone ketens ligt dat anders. Een event kan worden gepubliceerd zonder dat er direct een reactie volgt, en eventuele vervolgstappen kunnen verspreid in de tijd plaatsvinden. Door die loskoppeling expliciet te maken in de documentatie, voorkom je dat impliciete aannames ontstaan over volgorde of responstijden. AsyncAPI sluit hier goed op aan en is er ook gewoon voor gemaakt; het legt de nadruk op het event zelf en niet op de interactie eromheen.

Complexe/grote landschappen​

Hier zit een meerwaarde in die groter wordt naarmate ketens langer en complexer worden. In grotere landschappen, waarin meerdere systemen events publiceren en consumeren en waarin geen enkele partij het volledige overzicht heeft is het risico sterk aanwezig dat er geen eenduidig overzicht meer beschikbaar is en afhankelijkheden uit beeld verdwijnen. Kleine wijzigingen kunnen onverwachte effecten hebben, simpelweg omdat niet duidelijk is wie er allemaal geraakt wordt. In dat soort omgevingen fungeert AsyncAPI als een soort verkeerskaart: wellicht niet volledig tot in alle details, maar wel voldoende om inzicht te geven in de belangrijkste stromen en afhankelijkheden. Het maakt zichtbaar welke events bestaan, hoe ze zijn opgebouwd en waar mogelijke breekpunten zitten. Dat helpt teams niet alleen om hun eigen werk beter te begrijpen, maar ook om bewuster om te gaan met veranderingen.

Veranderlijk landschap​

Die veranderlijkheid verdient ook de aandacht in deze context. In systemen waarin berichten regelmatig evolueren, zoals uitbreidingen van payloads, nieuwe versies van API’s of aanpassingen in structuur, wordt het risico op misinterpretatie snel groter. Zonder expliciet contract is het dan lastig om te bepalen wat wel en niet een breaking change is, en waar compatibiliteit gewaarborgd moet blijven. AsyncAPI biedt hier houvast door schema’s en versies expliciet vast te leggen, waardoor wijzigingen niet alleen zichtbaar, maar ook toetsbaar worden. In combinatie met automatiseerbare tooling voor validatie en codegeneratie ontstaat zo een mechanisme dat helpt om veranderingen gecontroleerd door te voeren. Door wijzigingen expliciet te maken krijg je grip op versiebeheer en worden breaking changes zichtbaar in zowel inhoud als locatie. AsyncAPI’s strakke documentatie van wat een sender/receiver echt nodig heeft voorkomt eens te meer dat men stilletjes elkaars systemen breekt.

Complexe/grote berichten​

Los van alle landschap-eigenschappen is er ook op gebied van de berichten zelf een reden om AsyncAPI in gebruik te gaan nemen voor asynchrone API documentatie. Naarmate payloads groter en gelaagder worden, neemt de kans toe dat verschillende partijen dezelfde data op een andere manier interpreteren. Zeker in asynchrone communicatie, waar directe feedback ontbreekt, kan dat leiden tot fouten die pas laat aan het licht komen. Door de structuur en betekenis van berichten expliciet te documenteren, verklein je die interpretatieruimte. AsyncAPI dwingt je niet om die stap te zetten, maar faciliteert het wel op een manier die goed aansluit bij bestaande ontwikkelpraktijken. Ook hierin is de automatiseerbare tooling van toegevoegde waarde; de beheerlast van het bijhouden en valideren van alle versies + het opstellen van passende code kan met een druk op de knop per versie uitgevoerd worden (mits je dit hebt ingericht natuurlijk, maar dat spreekt voor zich).

Event-Driven omgevingen​

Al deze kenmerken komen samen in omgevingen waarin Event-Driven Architecture de norm is. Denk aan Kafka, RabbitMQ, PubSub en meer; zodra events fungeren als primaire vorm van communicatie, en messaging-platform protocollen de onderliggende infrastructuur vormen, ligt het gebruik van AsyncAPI voor de hand. Niet omdat het moet, maar omdat het aansluit bij de manier waarop het systeem is opgebouwd. Het biedt een gemeenschappelijke taal om events te beschrijven, los van het specifieke protocol of de implementatie, en maakt het mogelijk om documentatie, tooling en ontwikkeling beter op elkaar af te stemmen in een specificatie die gemaakt is om deze type zaken te beschrijven.

OAS als betere optie​

Kortom, AsyncAPI biedt een hoop mogelijkheden. Het is echter zeker niet alomvattend, ongeacht wat er op de Roadmap pagina staat. Uit onze eigen onderzoeken en use cases is duidelijk gebleken dat er situaties zijn waarin de toegevoegde waarde beperkt blijft. Om het verschil goed te duiden wil ik deze ook in enige mate van detail toelichten.

Simpele integraties; 1-op-1 koppelingen​

De eerste en misschien meest voor de hand liggende situatie is die van eenvoudige, 1-op-1 koppelingen tussen twee systemen. Wanneer zowel de producer als de consumer bekend en onder controle zijn van hetzelfde team, of wanneer de lijnen tussen producer en consumer zeer kort zijn is de noodzaak voor een uitgebreid contract vaak klein. De betrokken partijen hebben direct contact, wijzigingen kunnen afgestemd worden en de kans op onverwachte afhankelijkheden is gering. Naast een minimale noodzaak om het wél te doen is er ook een duidelijke reden om het niet te doen. Het introduceren van een uitgebreide specificatie en al het werk dat nodig is om dit op te stellen en bij te gaan houden gaat dan leiden tot extra beheerlast zonder dat daar een concreet voordeel tegenover staat.

Simpele/kleine berichten​

Een vergelijkbaar beeld ontstaat bij kleine of eenduidige berichten; denk aan simpele status berichten als een { "status": "ok" }. Wanneer de inhoud beperkt is en er weinig ruimte is voor interpretatie, voegt het modelleren van uitgebreide schema’s weinig toe. Het risico dat AsyncAPI hier probeert te ondervangen, namelijk misinterpretatie van complexe data in een uitgebreide en ontkoppelde keten, is simpelweg niet aanwezig. De investering in documentatie en tooling weegt dan al snel zwaarder dan de potentiële winst. Een goed voorbeeld hiervan is de situatie bij de RVIG zoals voorgedragen in de werkgroep. Zij hebben een simpele asynchrone API implementatie en is ook op onderzoek gegaan om te kijken of AsyncAPI hier een toevoeging kan zijn. Het gaat hier om een heel klein bericht in een omgeving die niet heel veel verkeer ziet. Hun conclusie was dat het opbouwen van AsyncAPI documentatie, het definiëren van Operations, Messages, Channels e.a. niets opleverde wat niet makkelijker met een asynchrone PubSub-based API in OAS documentatie te behalen viel. Ook liepen ze er tegenaan dat het definiëren van Channels vragen opwierp waar geen sluitend antwoord op bleek; richt je een Channel op per gebeurtenistype? Per persoon? Per abonnee? In alle gevallen ben je eigenlijk enorme bergen aan beheerlast aan het scheppen. Kortom, AsyncAPI was/is hier niet de uitkomst.

Low-use omgevingen​

Dan een klein maar toch noemenswaardig vervolg op het vorige punt, waarin we kijken naar de context waarin systemen opereren. In omgevingen waarin berichten weinig voorkomen of nauwelijks impact hebben, is de noodzaak voor strakke contracten beperkt. Denk aan je “nice-to-haves”, non-critical events die tevens zelden voorkomen en waar het de organisatie “niks” kost als het fout gaat of verkeerd geïnterpreteerd wordt. In zo’n situatie is het zeer aan te raden om voor een lichtere aanpak te kiezen dan een volledige AsyncAPI straat opbouwen.

Statische omgevingen​

In het verlengde daarvan lijkt AsyncAPI ook minder geschikt voor situaties die weinig tot niet veranderen over tijd. Zonder iteraties, uitbreidingen, nieuwe versies of in zijn geheel een noodzaak op aanhoudende governance is de meerwaarde van uitgebreide contractbeschrijving kleiner. Pak daar de toegevoegde beheerlast bij en je bent net als eerder meer werk aan het doen aan beheer opstellen dan dat het je uit handen neemt. Hoewel het van toegevoegde waarde kan zijn om dit wel te doen als de rest van de organisatie alles op deze wijze documenteert is AsyncAPI waarschijnlijk teveel gevraagd in use cases waarin niks gaat veranderen. Dan zouden een paar simpele regels documentatie voldoende kunnen zijn.

Onvolwassen organisaties​

Het moet toch ook genoemd worden: misschien wel de meest onderschatte factor is de organisatie zelf. AsyncAPI veronderstelt een bepaalde mate van volwassenheid in het omgaan met documentatie en contracten. Als specificaties niet worden bijgehouden, als er geen duidelijk eigenaarschap is of als afspraken niet worden nageleefd, verliest de documentatie snel zijn waarde. In het slechtste geval ontstaat er een situatie waarin de specificatie een verouderd of onjuist beeld geeft van de werkelijkheid, met alle risico’s van dien. In die zin geldt hier een eenvoudige maar belangrijke regel: slechte AsyncAPI is erger dan geen AsyncAPI. Dit geldt uiteraard voor elke standaard, maar het moet toch benoemd worden dat AsyncAPI hier echt geen uitzondering op is.

Voorlopige conclusie​

Alles bij elkaar zijn we tot nu toe op een genuanceerd beeld uitgekomen. AsyncAPI lijkt bijzonder krachtig in complexe, dynamische en ontkoppelde omgevingen waarin events een centrale rol spelen en waarin meerdere partijen onafhankelijk van elkaar opereren. In die context helpt het om structuur aan te brengen, afspraken expliciet te documenteren en veranderingen beheersbaar te maken. Tegelijkertijd is het geen vanzelfsprekende keuze voor elke vorm van communicatie, asynchroon of anderszins. Juist door kritisch te kijken naar de aard van het probleem en de context waarin het zich voordoet, kun je bepalen of de inzet van AsyncAPI daadwerkelijk bijdraagt aan een betere oplossing. We zijn nog niet zover, maar het begint er wel op te lijken dat een NL GOV profiel op den duur van toegevoegde waarde gaat zijn voor deze standaard.

Hopelijk heeft deze uiteenzetting geholpen met wat inzicht verkrijgen in wanneer AsyncAPI een oplossing kan zijn. Het kan echter goed zijn dat dit nog te abstract voelt, en dat men graag wil weten hoe een echte implementatie er nou uit zou komen te zien. Zoals al gezegd is dit alles nog een work-in-progress, maar dat neemt niet weg dat we vast een beetje vooruit kunnen kijken. In de laatste blogpost in deze reeks neem ik jullie mee in de combinatie van AsyncAPI met Cloudevents, om eens een schets te maken van hoe dit alles in zijn werk zou gaan als we het echt gaan gebruiken.

De vernieuwde Stelselcatalogus is nu live via stelselcatalogus.nl! De omgeving is gebruiksvriendelijker, actueler en beter voorbereid op de toekomst. Niet alleen de techniek en interface zijn vernieuwd, ook het onderliggende informatiemodel is verbeterd. Hierdoor kunnen onder meer specifieke relaties tussen gegevens worden gelegd.

Wie met data werkt voor maatschappelijke vraagstukken, weet hoeveel tijd gaat zitten in het vinden, verkrijgen en begrijpen van gegevens. Juist daarom zijn toegankelijke catalogi onmisbaar en is er in het Federatief Datastelsel (FDS) een catalogusfunctie voorzien.

Met behulp van metadata biedt de Stelselcatalogus inzicht in gegevens, begrippen en informatiemodellen, en in de relaties daartussen. Dat helpt om bestaande datasets beter te gebruiken bij analyse en het oplossen van maatschappelijke vraagstukken.

Wat is er nieuw?​

De technologie achter de catalogus is vernieuwd en sluit beter aan op moderne webstandaarden. De zoekfunctie en interface zijn verbeterd, zodat gebruikers sneller de juiste informatie vinden. De catalogus bevat nu naast informatiemodellen ook begrippenkaders. De vernieuwde structuur legt een stevige basis voor verdere uitbreiding en betere aansluiting op het Federatief Datastelsel.

Onderdeel van een groter geheel​

In de vernieuwde Stelselcatalogus vind je informatie over begrippen en informatiemodellen. Metadata van datasets en dataservices vind je via data.overheid.nl en developer.overheid.nl. Gezamenlijk vormen deze voorzieningen de ingang tot overheidsdata.

De Stelselcatalogus geeft overzicht in gegevens die binnen de overheid worden gebruikt, zoals gegevens uit Basisregistratie Personen (BRP), het Handelsregister en de Basisregistratie Kadaster (BRK). Bij ieder gegeven staat extra uitleg over betekenis, herkomst en registratie. Dat helpt beleidsmakers, architecten, data-analisten en uitvoeringsorganisaties om gegevens beter te begrijpen, te gebruiken en waar mogelijk te hergebruiken.

Zo draagt de vernieuwde Stelselcatalogus bij aan een overheid waarin data beter vindbaar, begrijpelijk en toepasbaar is. Meer informatie is te vinden op stelselcatalogus.nl.

Wij komen graag in contact met onze stakeholders. Via LogiusContactStelselcatalogus@logius.nl kun je met ons in contact komen.

Om dit alles te gaan bevatten is door de werkgroep eerst aangenomen om wat use cases te gaan aanpakken en gewoon te zien waar we tegenaan lopen wanneer AsyncAPI als standaard as-is wordt gebruikt. Hiermee konden we tegelijk technische affiniteit opdoen, iets van waarde opleveren voor partijen die daadwerkelijk asynchrone API’s ontsluiten, en informatie verzamelen voor het beantwoorden van de grote vraag: “moet dit een nieuwe standaard worden as-is, of is er een NLGov profiel nodig?” Met dit in het achterhoofd is een tweetal cases opgepakt en zijn we de diepte ingedoken, met regelmatige besprekingen in de werkgroep.

AsyncAPI​

Maar eerst even wat achtergrond en introductie voor wie nog niet bekend is met AsyncAPI. In het kort, AsyncAPI is een open source set aan standaarden en tools voor ontwikkelen en documenteren van asynchrone API’s en Event-Driven Architecture in zijn algemeen. Het is tevens een voortborduursel op het werk van OpenAPI Initiative, waarin door een toegewijd team van experts wordt gepoogd om een nieuwe standaard te bouwen voor asynchrone API’s binnen de context van Event-Driven Architecture. AsyncAPI is hierin geen runtime tool, het is voor documentatie, contract en standaardisatie voor Event-Driven systemen. Het helpt bij begrijpen wat er over de lijn gaat, waar die berichten leven, welke afspraken er gemaakt worden tussen partijen, en het automatiseren van documentatie, code en validatie. Dit is van toegevoegde waarde in asynchrone use cases; voor synchrone is OAS meer dan toereikend, ongeacht wat AsyncAPI op hun voorpagina heeft staan.

Op dit moment wordt er in een werkgroep van diverse experts gewerkt om AsyncAPI te vertalen naar de Nederlandse digitale overheid. Deze groep richt zich erop om een breed gedragen kennisplatform te bouwen, waar de volgende aandachtspunten op de voorgrond staan:

1. Uitzoeken hoe de standaard in elkaar zit; wat kun je ermee, hoe werkt het, welke tools zijn er? Etc.
2. Uitwerken waar de standaard wel en niet voor geschikt is
3. Specifieke use cases van ondersteuning voorzien in het uitwerken van hun implementatie van een asynchrone API keten, om daarmee ook punt 1 en 2 verder uit te werken.

De eerste observatie in de groep, op basis van hoe AsyncAPI zich op hun eigen website presenteert, is dat AsyncAPI vaak wordt gepositioneerd als de asynchrone tegenhanger van OpenAPI. Die vergelijking bleek in de praktijk niet dusdanig strak op te gaan. Waar OpenAPI draait om request-response interacties tussen bekende partijen, richt AsyncAPI zich op events, berichtenstromen en ontkoppeling. Dat verschil lijkt op papier misschien klein, maar werkt door in vrijwel elke keuze die je maakt: van hoe je documentatie structureert tot hoe je verantwoordelijkheden in een keten interpreteert. OAS zou wel degelijk voor asynchrone situaties gebruikt kunnen worden; PubSub webhooks worden bijvoorbeeld gewoon ondersteund in OAS.

Vingers aan de knoppen​

1-op-1 conversie​

Om beter grip op de nuances te krijgen hebben we een bestaande reeks API-specificaties waarin al sprake was van asynchrone communicatie omgezet naar een AsyncAPI documentatie; zie hier en hier voor links naar een aantal resultaten. In eerste instantie is er puur een 1-op-1 conversie gemaakt, met als doel om te zien hoe ver we kwamen zonder het onderliggende ontwerp aan te passen. Wat daarbij opviel is dat die conversie verrassend goed te doen is. Handmatige conversie van een relatief simpele API aan de hand van de specificatie was een goede eerste stap om de spec beter te leren kennen, maar kostte wel tijd. Desondanks bleek het relatief eenvoudig om Endpoints en Hostnames te vertalen naar Channels, Payloads naar Messages en bestaande schema’s grotendeels te hergebruiken. De beschikbare tooling helpt hier aanzienlijk bij; validatie, documentgeneratie en zelfs conversiefunctionaliteit maken het mogelijk om vrij snel tot een werkbare specificatie te komen.

In het uitvoeren van deze “simpele” conversie werd er een belangrijk punt zichtbaar. Een succesvolle conversie betekent namelijk niet automatisch dat je ook een betere of meer passende beschrijving hebt gemaakt van je systeem. In veel gevallen bleek de AsyncAPI-specificatie in essentie hetzelfde te beschrijven als de oorspronkelijke OpenAPI-variant, alleen in een ander formaat. Ja, het is nu in een documentatievorm die specifiek is toegespitst op asynchroon verkeer, maar de vraag blijft of het wel nodig is. Ja, de berichtenstroom was explicieter gemaakt, maar de onderliggende architectuur bleef ongewijzigd. Daarmee ontstaat een situatie waarin je wel asynchrone documentatie hebt, maar nog geen Event-Driven ontwerp. Kortom, we kunnen nog een stap verder.

Event-Driven herontwerp​

Voor één van de casussen hebben we dus precies dit gedaan; in plaats van een simpele conversie is er een volledig Event-Driven documentatie in AsyncAPI opgeschreven. Waar de 1-op-1 conversie nog sterk leunde op bestaande endpoints en interactiepatronen dwong het herontwerp ons om fundamenteel anders te kijken naar het systeem. De 1-op-1 conversie was een goede eerste stap in dit proces; doordat alles al naar AsyncAPI vertaald was konden bepaalde zaken zoals channels, operations, messages e.a. makkelijk overgenomen worden. Het resultaat is een ontwerp waarin Events werden leidend in plaats van Calls, meerdere Consumers konden onafhankelijk op dezelfde gebeurtenis reageren en de keten van acties werd losgekoppeld in plaats van expliciet georkestreerd. In die context kwam AsyncAPI veel beter tot zijn recht, omdat het precies datgene beschrijft waar het voor bedoeld is: het gedrag en de structuur van berichten in een ontkoppeld landschap. Voor de geïnteresseerden, hier is een link naar een EDA-versie van de inventaris API hier eerder gelinkt.

Deze stap vereiste uiteraard beduidend meer werk dan een 1-op-1 conversie. Waar de tooling goed ondersteunt bij het omzetten en valideren van specificaties, laat het de daadwerkelijke architectuurkeuzes volledig bij de gebruiker. Het herinterpreteren van bestaande documentatie naar een Event-Driven model vraagt om inhoudelijke keuzes, afstemming tussen betrokken partijen en een goed begrip van de implicaties van ontkoppeling. Met andere woorden: AsyncAPI faciliteert, maar dwingt niets af; dit is één van de schoonheden van de specificatie.

Tooling​

Ook op het gebied van tooling kwamen interessante observaties naar voren. Over het algemeen is de volwassenheid hoog; validatie werkt betrouwbaar, documentatie is snel te genereren en codegeneratie biedt duidelijke voordelen in termen van consistentie en snelheid. Er zijn diverse templates voor allerlei soorten code en applicaties beschikbaar “out of the box”, met ruimte om zelf je eigen templates te ontwikkelen en beheren. Er zit hier op dit moment wel een sterke externe afhankelijkheid in; denk hierin aan de black-box nature van de default templates, versies van tooling en het gekozen perspectief binnen de specificatie. In één geval bleek bijvoorbeeld dat om een bepaald type code te genereren de documentatie naar een lagere versie gebracht moest worden, maar dat daardoor ook het perspectief van de API documentatie zou wijzigen, namelijk van producer naar consumer. Dit was al eerder een vraag binnen de werkgroep: vanuit welk perspectief moet men AsyncAPI lezen? Het staat in de specificatie aangegeven (3.x en hoger schrijven vanuit de producer, alles daaronder vanuit consumer), maar dit wordt niet meteen duidelijk uit een API document zelf. Dergelijke afhankelijkheden en mogelijkheden tot foute interpretatie maken het des te belangrijker dat er een gebruikstandaard wordt opgesteld, hetzij binnen een organisatie danwel binnen de gehele context van de Nederlanse Overheid.

Toepasbaarheid en Toekomst​

Uit deze voorbeelden en degenen die door anderen in de werkgroep zijn aangedragen zijn we naast beter begrip van de technische werking ook een stuk wijzer geworden over de toepasbaarheid van AsyncAPI. In omgevingen waarin meerdere systemen onafhankelijk van elkaar events publiceren en consumeren, en waarin niet altijd vooraf bekend is wie welke informatie gebruikt, helpt een expliciet contract enorm om overzicht te creëren. Zeker wanneer berichten complex zijn of regelmatig veranderen biedt de combinatie van duidelijke schema’s en tooling voor validatie en generatie een stevige basis om fouten en misinterpretaties te voorkomen. Hetzelfde geldt voor bredere Event-Driven landschappen, waarin inzicht in de keten en de impact van wijzigingen cruciaal is om het geheel beheersbaar te houden.

Wanneer AsyncAPI minder waarde toevoegt​

Daar tegenover staan situaties waarin die meerwaarde een stuk minder evident is. In eenvoudige koppelingen tussen twee systemen, zeker wanneer beide onder dezelfde verantwoordelijkheid vallen, voegt het expliciet modelleren van events en contracten vaak weinig toe. Hetzelfde geldt voor kleine, eenduidige berichten of omgevingen waarin nauwelijks sprake is van verandering over tijd. In dat soort gevallen kan de overhead van uitgebreide specificaties en bijbehorende tooling zwaarder wegen dan de voordelen die het oplevert. Sterker nog, wanneer documentatie niet actief wordt bijgehouden, kan het zelfs een risico vormen doordat het een vertekend beeld geeft van de werkelijkheid.

Conclusie​

De belangrijkste les die uit deze exercitie naar voren komt, is dan ook dat AsyncAPI vooral gezien moet worden als een middel, en niet als een doel op zich. Het is een krachtig instrument om asynchrone communicatie inzichtelijk te maken, te standaardiseren en deels te automatiseren, maar het vervangt geen architectuurkeuzes, geen governance en geen samenwerking tussen teams. Of het daadwerkelijk waarde toevoegt, hangt sterk af van de context waarin het wordt toegepast en de mate waarin organisaties bereid zijn om de bijbehorende werkwijze te omarmen. Dit is echter een onderwerp en-sich, en dus spaar ik die op voor de volgende blogpost!

Digitale kaartinformatie, ook wel geo-informatie genoemd, is voor een organisatie als het Kadaster onmisbaar. De eenvoudigste manier om geo-informatie te bekijken en te gebruiken, is via een online kaartviewer. Diverse kaartviewers, zoals de PDOK Viewer, het WOZ-waardeloket en de BAG Viewer, zijn door het Kadaster ontwikkeld om geodata eenvoudig te raadplegen en te gebruiken.

Wat minder zichtbaar is bij het gebruik van deze viewers, is dat ze 'onder de motorkap' dezelfde componenten gebruiken: de Generieke Geo Componenten.

Waarom Generieke Geo Componenten?​

Binnen het Kadaster worden veel kaartviewers ontwikkeld voor interne en externe doeleinden. We hebben ze nooit officieel geteld, maar naar schatting zijn het er 40 à 50. Vaak worden deze viewers ontwikkeld door afzonderlijke ontwikkelteams.

Het BAG-team is bijvoorbeeld verantwoordelijk voor de volledige dienstverlening rondom de Basisregistratie Adressen en Gebouwen (BAG). Zij zorgen ervoor dat bronhouders (gemeenten) BAG-data kunnen registreren, dat deze correct wordt opgeslagen in de landelijke voorziening en dat de gegevens via API's en andere webservices beschikbaar worden gesteld aan gebruikers. Daarnaast zijn zij ook verantwoordelijk voor de ontwikkeling en het beheer van de BAG Viewer.

Doordat veel teams op deze manier werkten, ontstond er zo'n tien jaar geleden een versnipperd landschap aan kaartviewers. De viewers maakten gebruik van verschillende technieken, zagen er onderling anders uit ondanks dezelfde huisstijl en voldeden niet altijd aan eisen op het gebied van toegankelijkheid en responsiveness. Daarbij lag de focus van veel ontwikkelteams vooral op backends en databases, waardoor het ontwikkelen en beheren van een kaartviewer er vaak 'bij' werd gedaan. Dit leidde ertoe dat in elk team telkens opnieuw het wiel werd uitgevonden.

Om dit te doorbreken zijn de Generieke Geo Componenten ontwikkeld: flexibele softwarebouwstenen waarmee ontwikkelaars, ook zonder veel frontendkennis, eenvoudig een online kaartviewer kunnen maken. Ze werken met de geo-informatiestandaarden die PDOK gebruikt voor open geodata en ondersteunen het principe 'data bij de bron'. Ook voldoen ze, waar mogelijk, aan de toegankelijkheidsrichtlijnen (WCAG), al geldt voor geo-informatie deels een uitzondering.

Waarom open source?​

Al vroeg in de ontwikkeling van de Generieke Geo Componenten ontstond het idee om deze buiten het Kadaster beschikbaar te maken. De componenten zijn namelijk gebaseerd op open‑sourceframeworks zoals OpenLayers en Angular. Daarnaast zagen we dat andere overheidsorganisaties tegen vergelijkbare uitdagingen aanliepen, of juist onvoldoende capaciteit hadden om zelf een kaartviewer te ontwikkelen. Open software kan bovendien helpen bij het vergroten van de adoptie van open data en open standaarden.

Toch strandde dit plan eind 2017, na het verschijnen van een rapport van Gartner. Hierin werd gewezen op mogelijke juridische risico's in het kader van de Wet Markt en Overheid. De focus verschoof daarom naar intern gebruik, terwijl we verder werkten aan het verbeteren van de componenten en het stimuleren van het gebruik binnen het Kadaster.

De ambitie verdween tijdelijk naar de achtergrond, maar bleef bestaan. Inmiddels zijn zowel het overheidsbeleid als het Kadasterbeleid rond open source gewijzigd. We zijn dan ook blij dat we tijdens de Open Geodag van 12 mei de Generieke Geo Componenten alsnog hebben kunnen vrijgeven.

Een bijkomend voordeel is dat de componenten in de tussentijd rijker zijn geworden in functionaliteit en zich in de praktijk hebben bewezen: ze worden inmiddels in zo'n 30 applicaties binnen het Kadaster gebruikt.

Actief samenwerken aan doorontwikkeling​

We nodigen iedereen uit om een kijkje te nemen op https://www.generiekegeocomponenten.nl.

Hier kun je voorbeelden bekijken, de componenten gebruiken en bijdragen aan de verdere ontwikkeling. Op de website vind je ook een link naar GitHub en technische documentatie om de componenten te installeren en te configureren. Voor het Kadaster is dit een van de eerste serieuze open‑sourcesoftwarepublicaties. We kijken uit naar de extra dynamiek en samenwerking die dit oplevert voor de verdere doorontwikkeling van de componenten.

Op woensdag 17 juni organiseren we een nieuwe developer.overheid.nl meetup in Utrecht. Een middag voor developers, architecten, platform engineers, tech leads en makers binnen de overheid die willen bouwen, leren en ervaringen uitwisselen.

Geen beleidsverhalen, maar concrete praktijkvoorbeelden, demo's, open source tooling en gesprekken met mensen die hier dagelijks aan werken.

Op het programma​

• Platform engineering — Anne Schuth
  Waarom is de Nederlandse overheid misschien wel het grootste softwarebedrijf van Nederland. En waarom moeten we ons ook zo organiseren.

• AI Skill: publiccode.yml generator — Tom Ootes
  Hoe je met AI Skills automatisch een publiccode.yml genereert en AI inzet binnen je ontwikkelproces.

• DON-checker — Dimitri van Hees
  Live demo van de vernieuwde DON-checker voor het toetsen op standaarden en kwaliteit.

• Code.overheid.nl — Johan Groenen
  Over code.overheid.nl; een nieuwe gedeelde gitomgeving voor de overheid, gebouwd op Forgejo, opgezet door OSPO BZK als antwoord op de groeiende vraag naar digitale soevereiniteit en een alternatief voor GitHub.

• OpenKAT — Jan Klopper
  Een open source securitytool met een actieve community en slimme plugins ("boefjes") voor het analyseren van netwerken en systemen.

• Open mic & vooruitblik
  Welke tooling, standaarden of use cases wil jij de volgende keer zien?

• Borrel bij Ruig

Praktische informatie​

Word contributor.

We zien je op 17 juni!

Bij het bevorderen van adoptie van standaarden is het van groot belang dat de softe kant op orde is. De keuze om een standaard te implementeren heeft een grotere impact als een bestuurder die maakt, dan één individuele developer. Zelf doe ik mee aan de werkgroep "Adoptie van standaarden" binnen het Federatief Datastelsel (FDS), om te analyseren welke activiteiten nuttig zijn om adoptie te bevorderen.

Het verkopen van "nee"​

Standaardisatie is in essentie de kunst van het verkopen van "nee". Voorheen was elke gekozen oplossingsrichting mogelijk, met een standaard worden daar keuzes in gemaakt. Dit is per definitie restrictief: eerst mocht je alles en nu niet meer. Onbewust is dat ook het eerste signaal wat mensen ontvangen: "Nu moet ik het op deze specifieke manier doen, waarom dan?".

Bij het bevorderen van standaardisatie is het cruciaal om te realiseren dat restricties nooit fijn zijn. Elk mens waardeert de (persoonlijke) keuzevrijheid, zeker in het federatieve overheidslandschap van honderden overheidsorganisaties die grotendeels autonoom beslissingen willen maken. Daarom is in mijn optiek de focus op "nu kan je dit niet meer" geen handige tactiek. Je staat al 1-0 achter voordat het gesprek begint.

De focus verleggen naar "als we dit afspreken, dan kan je ineens X-Y-Z" is een positievere boodschap. Door af te spreken om alle mogelijke gegevens die uitgewisseld kunnen worden in formaat F vast te leggen, is het bijvoorbeeld mogelijk om efficiëntere aansluitingen te realiseren. De voordelen bij gegevensuitwisseling zijn er voor beide partijen:

1. de afnemer weet dat het er altijd vanuit kan gaan dat het in formaat F is vastgelegd, zodat elke uitwisseling op dezelfde manier verloopt
2. de aanbieder heeft baat bij uniformiteit omdat hij bij de nieuwe integratie van een afnemer exact hetzelfde endpoint kan bieden

Hier hebben beide partijen baat bij, ook al mogen ze nu minder dan wat voorheen toegestaan was. Restricties leveren in dit geval wel degelijk waarde op.

Hoe krijgen we de focus op de positieve kant?​

De uitdaging bij standaardisatie is om de focus van restricties te verleggen naar de positieve kant. Dit is het gespreksonderwerp van de werkgroep "Adoptie van standaarden" bij het FDS. Vanaf de eerste werksessie werd de focus gelegd op de softe kant, iets waar ik positief verrast door was. "Fijn dat er gelijkgestemden hier bijeenkomen die realiseren hoe belangrijk die softe kant is" dacht ik toen.

Het was wel nog zoeken hoe we deze softe kant kunnen belichten. We vroegen ons af wie de belanghebbenden zijn bij de keuze voor standaarden en wat hun beweegredenen zijn. Hiervoor hebben we enkele persona's uitgewerkt, om structuur te kunnen geven aan de discussies.

De persona's waar we voor nu op focusen zijn:

1. Programmamanager bij een overheidsorganisatie
2. Architect bij een overheidsorganisatie
3. Developers (bij een leverancier)

Elke persona heeft andere wensen, eisen en bewegingsruimte. Tevens heeft de ene persona meer invloed dan de andere op bepaalde gebieden. Hierbij is het belangrijk om te weten "wie er aan welke tafel zit" om te bepalen waar het gesprek over een standaard plaats vindt.

De bestuurlijke hoek bepaalt​

Voor de bestuurlijke hoek is het van belang om te begrijpen wat er speelt en hoe een oplossing daaraan bijdraagt. Vaak wordt op dit niveau nagedacht over prioriteit, tijd en geld. Met standaarden is het dus van belang om duidelijk te krijgen hoe een standaard bijvoorbeeld tijd of geld bespaart, waardoor het prioriteit verdient.

Er is ingezet om een overzicht te krijgen op welke gebieden bepaalde standaarden de meeste waarde realiseren. Hieruit is een overzichtsplaat voortgekomen die laat zien voor welke stelselfuncties binnen het FDS welke standaarden passen:

Deel van de overzichtsplaat zoals gepubliceerd op de website van FDS (geraadpleegd op 2026-04-01)

Zo'n overzicht is te printen voor op een banner, of eenvoudig toe te voegen aan een presentatie. Dat is ook de werkomgeving van de bestuurlijke hoek: overleggen met anderen wat er gedaan moet worden. Hierbij is een overzicht nuttig om te laten zien wat er mogelijk is en dat er al analyses zijn gedaan welke standaard het beste toepasbaar is.

Architecten als sturing​

Bestuurders vragen zich ook vaak af: "Oke, maar is dit wel uit te voeren in mijn organisatie?" Hierbij is het noodzakelijk om het technische landschap van een organisatie te kennen en hier een visie op te hebben. Daar komt de rol van een architect bij kijken, waarbij het voor standaarden belangrijk is dat een architect begrijpt hoe zo'n standaard past in het totaalplaatje.

Om dit duidelijker te krijgen zijn er handreikingen geschreven. De eerste versie van de handreikingen staan inmiddels online op NORA.

De handreikingen gaan meer in detail ten opzichte van de overzichtsplaat. Ze bevatten generieke informatie over de standaard, de impact die het heeft, maar ook de relaties tot andere standaarden. Dat sluit mooi aan op de originele vraagstukken waar een architect aan werkt: hoe past in het geheel?

Mogelijk valt het ook op hoe de handreikingen een positieve toon hebben. Er wordt aangegeven wat er mogelijk is als de standaard wordt geïmplementeerd en aan welke architectuurprincipes ze invulling geven. Daarnaast wordt er ook ingegaan op impact, want er zullen altijd ook andere consequenties zijn waar rekening mee moet worden gehouden.

Developers als de doeners​

Als een bestuurder het nut inziet en een architect de mogelijkheden, is het nog wel de zaak dat het ook uitvoerbaar is. Hier komt de doelgroep van developers (al dan niet in-house of werkzaam bij een leverancier) in beeld. Developers willen graag concrete instructies hoe een standaard toe te passen is en hoe het mogelijk is om te checken of daaraan wordt voldaan.

Deze vraagstukken worden dan bij uitstek hier in de kennisbank op developer.overheid.nl beantwoord. Bijvoorbeeld voor Logboek Dataverwerkingen zijn er concrete codevoorbeelden en links naar referentie-implementaties die inspiratie kunnen bieden aan de doeners.

Om te checken of er wordt voldaan aan een standaard kunnen validators worden gebruikt. De OAS checker is gebouwd om geautomatiseerd te valideren of een OpenAPI specificatie voldoet aan de REST API Design Rules. Validators worden steeds belangrijker, zeker in een tijdperk waarin code genereren met behulp van AI wordt toegepast.

Conclusie: de crux van adoptie zit in de gelaagdheid​

Elk van deze persona's heeft invloed op de (mogelijke) adoptie van een standaard. Als op een van de lagen het nut niet wordt gezien, het onduidelijk is hoe het past in het geheel of dat het niet uit te voeren is, resulteert dat vaak in het wegblijven van adoptie. Het scherp hebben van de eisen van een doelgroep helpt in het positief positioneren van een standaard.

Focus niet op maar één persona in de hoop dat het balletje dan vanzelf gaat rollen. Analyseer of een standaard iets mist aan communicatie op een bepaalde laag en focus daar op. Mijn hoop is dat de werkgroep later met nog meer informatie komt hoe dit aan te pakken.

Vanuit dit besef heeft OSPO BZK zich hard gemaakt voor de opzet van code.overheid.nl, in de vorm van een Forgejo instance.

Voor meer informatie over waarom Forgejo nou precies de juiste keuze is, verwijs ik je graag door naar de blogpost van Jan Vlug: "Aanbeveling voor de Git-werkplaats van de overheid".

Onmisbare schakel​

Als developer.overheid.nl is het ons doel om het leven van developers zo makkelijk mogelijk te maken en die developer in staat stellen om hoge kwaliteit software te bouwen.

De manier waarop we daar nu in voorzien is door middel van een kennisbank, tooling en een aantal producten. Ook draaien we verschillende checks op ons Open Source- en API-register en zorgen we zo voor kwaliteitsmonitoring. Echter zijn we voor het vullen van beide registers afhankelijk van organisaties voor het inzenden van hun repositories en API's. Bovendien hebben we geen directe toegang tot deze git omgevingen en kunnen we niet direct samenwerken met deze organisaties om bijvoorbeeld templates, tools en pipelines te delen.

Hoe mooi zou het zijn als we juist met z'n allen, dus met welwillende developers en organisaties een eigen gitplatform bouwen, zodat we onze tooling en zo onze werkwijzen gemakkelijk met elkaar kunnen delen. Pas dan zijn we echt in staat om ook gezamenlijk aan tooling te werken. Het stelt ons in staat om allemaal stukje bij beetje op dezelfde manier te gaan developen. Hier zie ik een grote rol voor code.overheid.nl weggelegd.

Dat is de kans die we nu hebben, dat we eindelijk een plek hebben waar we kunnen samenwerken en van elkaar kunnen leren.

Gina Plat van OSPO BZK

Zo beginnen we​

Hoe beginnen we hier mee? Door als verschillende organisaties met elkaar in gesprek te gaan over wat we nog nodig hebben om het platform op dagelijkse basis te kunnen gebruiken. En nog belangrijker, dat we beginnen te bouwen. Dat kan om te beginnen gewoon door middel van het inschieten van issues, om het gesprek te starten, en door middel van het maken van PR's.

De doelgroep zit aan tafel​

Wat mij betreft is de insteek van code.overheid.nl slim omdat je niet iets bouwt voor een gebruikersgroep (developers) maar met. Dit minimaliseert de kans dat je energie in iets stopt waarvan je achteraf moet concluderen dat het helemaal niet nuttig was.

En omdat de organisaties zelf ook energie stoppen in het bouwen van features, en dus skin in the game hebben, zullen ze eerder geneigd zijn het gebruik ervan aan te moedigen of te verplichten.

Boris van Hoytema van OSPO BZK

Pilot​

Op dit moment bevindt code.overheid.nl zich in de pilotfase. Dit betekent dat nog niet iedere overheidsorganisatie zich kan aanmelden en er gebruik van kan maken. De reden hiervoor is dat er gekozen is voor een graduele aanpak waarbij langzaam maar zeker een volwaardig gitplatform ontstaat.

Nog niet af​

Op dit moment kan dus nog niet de hele overheid ge-onboard worden, maar dat is in mijn optiek logisch. We moeten voorkomen dat het beeld ontstaat dat het nog niet af is, want het is in feite nog niet af, maar dat komt vooral doordat we het nog niet gebouwd hebben.

Meedoen​

Maar heeft jouw team bijvoorbeeld al ervaring met Forgejo en zijn jullie nu al zelf nuttige features aan het bouwen? dan is het mogelijk om nu al aangehaakt te raken. Hiervoor kan je contact opnemen met: codeplatform@rijksoverheid.nl.

Herinnering aan mezelf​

Deze blogpost wil ik ook graag gebruiken als een herinnering aan mezelf om me te commiteren aan code.overheid.nl. Het blijven zorgen voor een project in de vorm van issues, ideeën en pull requests is iets wat een hoop geduld vereist. Vooral omdat je er ineens voor moet gaan samenwerken.

Dat zie ik ook gebeuren bij de publiccode.yml-standaard waaraan ik bijdraag. De meeste tijd gaat zitten in het koppelen van mensen en het bespreken van ideeën, voordat het daadwerkelijk in de standaard zelf terecht komt.

Conclusie​

Bij deze dus de uitnodiging om code.overheid.nl in de gaten te houden en indien mogelijk mee te bouwen. Alleen samen komen we tot een volwaardig Github alternatief.

Ben je klaar om mee te bouwen? Meld je dan aan via de "Meedoen"-sectie hierboven.