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.

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?

In de voorgaande blogposts hebben we gekeken naar wat AsyncAPI is, hoe het zich in de praktijk gedraagt en in welke situaties het daadwerkelijk waarde toevoegt (of juist niet). Daarmee staat er een grove leidraad voor wanneer AsyncAPI te implementeren, en is de kernvraag van de werkgroep in zekere mate beantwoord. Dit is natuurlijk niet voldoende. Los van dat de kernvraag van de werkgroep nog een lopende discussie is lijkt het logische vervolg om te gaan kijken naar hoe dit alles daadwerkelijk geïmplementeerd kan/moet worden. In deze blogpost heb ik gepoogd om vast een stukje vooruit te kijken, met als kern de vraag: hoe zorg je ervoor dat events niet alleen goed beschreven zijn, maar ook consistent en interoperabel worden uitgewisseld tussen systemen?

Frank Terpstra opende de API-track plenair.

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.

In een eerdere blogpost zijn de eerste bevindingen van de werkgroep AsyncAPI gedeeld na het uitwerken van een tweetal use cases waarin asynchrone API’s van OAS naar AsyncAPI werden omgezet. Daarbij werd duidelijk dat AsyncAPI op zichzelf geen wondermiddel is, maar vooral een krachtig instrument dat helpt om asynchrone communicatie inzichtelijk en beheersbaar te maken. De overkoepelende vraag is nog echter niet behandeld: wanneer gaan we het dan wel, en wanneer niet gebruiken? In deze blog ga ik dieper in op de situaties waarin AsyncAPI wel geschikt lijkt, en in welke situaties het van weinig toegevoegde waarde lijkt te zijn.

De afgelopen periode hebben we binnen developer.overheid.nl samen met de Werkgroep AsyncAPI geëxperimenteerd met het toepassen van AsyncAPI in een aantal concrete casussen. Het doel van deze werkgroep is om te onderzoeken in welke mate AsyncAPI als nieuwe standaard voor de Nederlandse overheid geaccepteerd dient te worden. Niet zozeer om vast te stellen of het werkt, maar vooral om te begrijpen waar het in de praktijk daadwerkelijk waarde toevoegt, en waar het vooral extra werk introduceert zonder duidelijke meerwaarde. De technische werkbaarheid van de specificatie is door diverse use cases aangetoond; de vraag wanneer we het zouden moeten gebruiken is op dit moment dé kernvraag. Ik wil jullie in een reeks aan blogposts graag meenemen in waar de werkgroep nu staat m.b.t. AsyncAPI en hoe we de toekomst voor ons zien.

Op 31 oktober 2024 publiceerde Geonovum voor het eerst een JSON-schema bij een informatiemodel. Het betrof de publicatie van versie 3.0 van het Informatiemodel Externe Veiligheid: (IMEV). Daarnaast is er ook een suggestie voor een OpenApi Specificatie (OAS) gepubliceerd. In deze blog worden de ervaringen gedeeld die Geonovum daarmee heeft opgedaan in de hoop dat anderen daar van kunnen leren.

Ruim zeven jaar geleden werd het traject afgerond om de OpenAPI Specification (OAS) op de pas-toe-leg-uit-lijst van het Forum Standaardisatie te krijgen. Sindsdien is versie 3.0 de verplichte standaard voor overheids-API's. En dat was nog steeds zo, ondanks dat de volgende versie 3.1 al lang beschikbaar is. Tot deze week. Het standaardisatieproces voor OpenAPI 3.1 is eindelijk hervat. In deze blogpost leggen we uit waarom dit een belangrijke stap is waar veel ontwikkelaars op hebben gewacht.

Ondergetekende met het bewijs dat OpenAPI verplicht werd gesteld voor REST API's van de overheid, ruim zeven jaar geleden.

Als je gaat starten met het ontwikkelen van een API zijn er verschillende manieren om dit aan te pakken. In de praktijk zie je grofweg 2 verschillende methoden: "design-first" en "code-first". In dit artikelen leggen we uit wat de verschillen zijn en waarom de "design-first" aanpak wat ons betreft de voorkeur heeft.

Al sinds 2020 staan de REST API Design Rules op de pas-toe-of-leg-uit lijst van het Forum Standaardisatie, wat maakt dat deze verplicht zijn gesteld voor alle Nederlandse overheidsorganisaties. Deze design rules beschrijven een set regels waar een REST API aan zou moeten voldoen, met als doel meer uniformiteit aan te brengen in het informatielandschap van de overheid. In dit artikel geven we een aantal argumenten waarom API design rules zo waardevol zijn.