Notulen expert meeting 12 februari 2025

[TimvdLippe]

Woensdag 12 februari 2025 heeft Logius beheer (@sanderke, @TimvdLippe en @TheBonheurs) gesproken met @dvh, @fterpstra en @joostfarla over de toekomst van de API Design Rules standaard. Hierbij lag de focus op de strategie in relatie tot developer.overheid.nl (DON) en het bevorderen van adoptie bij bestaande APIs.

Wat is het entrypoint van een API voor DON?

Tim: Op dit moment staan er verscheidene APIs in de de API catalogus van DON. Deze APIs scoren wisselend, met als interessant datapoint dat 11% van de APIs op dit moment de Open API specification (OAS) op de juiste locatie publiceert. Hoe zorgen we ervoor dat APIs aangeleverd en up-to-date kunnen blijven?

Dimitri: We moeten het aanmeldformulier op DON aanpassen zodat die een locatie van een OAS neemt.
Hiermee redeneren we alles uit de OAS, ook al staat hij op de verkeerde plek.
We vervangen de validator (die echte requests/tests doet) door de linter (die enkel statisch checkt wat de OAS specificeert)
SURF heeft een open source project om de OAS te vergeleken met de daadwerkelijke implementatie

Joost: Veel van de design rules zijn niet te verifieren op basis van enkel de OAS. Missen we dan niet de effectiviteit?

Frank: Met een simplere linter kunnen we het promoten in workflows (CI/CD, local checks) ook via bijvoorbeeld het Rijks ICT gilde

Tim: Op DON kunnen we blog posts publiceren die uitleggen hoe de linter kan worden aangezet bij systemen zoals GitHub, GitLab, NPM, etc...
De validator was erg uitgebreid, maar veel APIs voldoen er nog niet aan. Als we met de linter beginnen dan kunnen we een simplere opstap maken voor organisaties om mee te komen. In de toekomst kunnen we dan naar verscherpingen kijken.
Opschrijven van de linter steps geeft Logius beheer ook beter inzicht of design rules technisch haalbaar zijn/automatisch te verifieren. Automatisch verifieren heeft de voorkeur, voor schaalbaarheid en draagvlak.
Qua aanbod op DON: suggestie om het contactformulier te vervangen door enkel 1 veld voor OAS locatie, alles van daaruit deduceren.

Dimitri: Daarom vonden wij het ook belangrijk dat het info.contact veld ingevuld is, zodat we contact kunnen opnemen aan de API owners mochten wij issues vinden na het runnen van de linter.

Tim: Op basis van huidige implementaties kunnen we ook design rules opstellen. Starten bij de werkelijkheid en op basis daarvan definieren wat de status quo is (gegeven dat die oke is).

Status van OAS 3.1 op PTOLU-lijst

Dimitri: OAS 3.1 kan ook meer beschrijven, zoals webhooks. Misschien hiervoor nieuwe design rules?

Tim: Verschil in velden is ook belangrijk. Niet alle velden zijn even cruciaal voor een goed gedocumenteerde API. Als een API op DON wil, dan beschrijvingsveld verplicht stellen. Maar voorbeelden zijn optioneel (kan een API beter op de kaart stellen, maar is niet vereist).

Frank: Wat is de status van OAS 3.1? Kunnen we die ondertussen weer aandragen?

Dimitri: 3.1 is toch backwards compatible?

Frank: Niet per se, hangt af van het JSON schema. Is technisch gezien een breaking change. Tooling is veel beter dan bij originele aanmelding 2 jaar geleden.

Dimitri: Vooral een tooling kwestie voor JSON schema? Je kan OAS 3.1 op een huidige API zetten en zou moeten werken. Misschien dat de tools het dan niet aankunnen.

Tim: We zoeken contact met Forum Standaardisatie over de status. 3.1 is nu kansrijker, mogelijk na ADR 2.0.

Dimitri: We kunnen bij DON ook checken of bij de huidige APIs in de API catalogus die zouden breken als we ze updaten naar 3.1. Schema's zijn van toegevoegde waarde, bijvoorbeeld om te refereren naar standaard registers en makkelijk op te vragen/integreren in je API.

Samenwerking met kennisplatform APIs (KPAPI)

Frank: Volgende bijeenkomst op 26 maart. Interesse voor OAuth om te presenteren over nieuwe iGov versie op PTOLU-lijst.

Tim: We willen ook presenteren over ADR 2.0 met vergelijkbare inhoud van recent Technisch Overleg (TO).

Frank: Contact opnemen met Geonovum voor inhoudelijke presentaties.

Dimitri: Duidelijker krijgen wie waar verantwoordelijk is. Issues bij DON worden doorverwezen naar KPAPI, maar soms ook naar Logius omdat het een beheerkwestie is.

Tim: Logius is beheerder, geen bouwer van APIs. Daarom is inhoudelijke input nog steeds nodig vanuit KPAPI. Eens dat hier meer duidelijkheid in moet komen. Nu worden mensen constant doorverwezen.

Dimitri: Is beheerder betrokken bij werkgroepen van KPAPI?

Frank: Waardevol om inhoudelijke kennis te houden bij KPAPI. Voorheen Kadaster voornamelijk als trekkende rol, nu is dat Logius. Voorstel om TO en bijeenkomst werkgroep samen te voegen. Desnoods verschillende voorzitters, maar wel in 1 sessie. Bijvoorbeeld de werkgroep beveiliging met het TO OAuth. Als er meer betrokkenen zijn bij werkgroep, dan ook groter draagvlak voor beslissingen in TO. Samenvoeging kan bij volgend TO op 10 april 2025.

Tim: Bij samenvoeging ook duidelijker dat issues gezamenlijk worden aangepakt in 1 sessie. Voorkomt onduidelijkheid zoals Dimitri eerder aangaf.

Opzetten werkgroep notificeren

Tim: Er is vraag vanuit meerdere organisaties voor notificeren.

Frank: Er moet actief worden gezocht naar een trekker voor de werkgroep Notificeren. Ook in verband met Async API. Mogelijk Stas? Stas en Frank gaan samen zitten om dit te bespreken

ADR in relatie tot andere standaarden

Joost: Doet nu onderzoek naar de relatie van ADR met andere standaarden. Mogelijk wringt het. Als er concrete problemen zijn komen hier waarschijnlijk wijzigingsvoorstellen van op de ADR.

Frank: Bedoel je hiermee bijvoorbeeld OData en OAS?

Tim: Voor OData hebben we een wijzigingsvoorstel gestart voor het definieren van een root pagina. Wel belangrijk om ADR niet teveel te laten groeien en zo onbedoeld meer conflicten te creeren.

Joost: Intentie om design rules meer open te stellen voor opties. Zodat bij verschillende APIs er ruimte is, zoals met OData.