Thema Werken met API's

Laatst bewerkt: 14 december 2022, 16:50:48

API-referentiearchitectuur (ARA)[bewerken]

Ara.png

In 2017 zijn gemeenten, VNG en leveranciers onder de naam ‘Common Ground’ een nieuwe informatiekundige weg ingeslagen. Eén gevolg was het ontwikkelen van nieuwe API-standaarden die aansluiten bij het vijflagenmodel en de REST-architectuurstijl volgen.

Naar aanleiding van de eerste ervaringen met implementatie van deze standaarden is een aantal vraagstukken ontstaan dat niet gaat over individuele standaarden, maar raakt aan alle API-standaarden voor gemeenten.

Het gaat hierbij om concrete opgaven als het bepalen van de aanpassingen van API-standaarden om aan te kunnen sluiten bij eerder dit jaar beschreven oplossingen voor toegangsbeheer. Maar ook om het beantwoorden van meer fundamentele vragen bij thema’s als performance (bij het bevragen van gegevens uit meerdere bronnen ineens) en consistentie (tussen gegevens in meerdere bronnen).

Het antwoord op deze vragen vormt een gezamenlijke basis of ‘fundament’ waarop we de komende jaren bij de ontwikkeling van API-standaarden verder kunnen bouwen. Dit fundament noemen we de API-referentiearchitectuur (ARA). Ontwikkeling daarvan is een voorwaarde voor doelmatige, op elkaar aansluitende API-standaarden van goede kwaliteit.

Aanleiding en belang[bewerken]

Standaarden vormen een essentiële schakel in de transitie naar een informatievoorziening die aansluit bij de visie Common Ground. Dit belang wordt ondersteund door het recent (april 2022) door PBLQ uitgebrachte advies over 'versterking van bestuurlijke sturing op Common Ground' en het verslag van de meerdaagse Common Ground (september 2022). In beide documenten komen we dan ook veelvuldig begrippen als 'uitwisseling', 'bronnen' en natuurlijk 'standaarden' tegen.

Wordcloud met begrippen uit het rapport van PBLQ over bestuurlijke sturing Common Ground (links) en het verslag van de meerdaagse Common Ground (rechts)

Naar aanleiding van implementatie door gemeenten van de eerste API-standaarden die de REST-architectuurstijl volgen, constateren we echter een aantal problemen aan die niet zozeer te maken hebben met individuele API-standaarden als wel met de meer generieke vraag hoe hoe je binnen de beperkingen van deze stijl nu eigenlijk een goede standaard ontwikkelt. Denk hierbij aan issues als:

  • onvoldoende performance om standaarden in de praktijk te kunnen gebruiken;
  • (te) grote complexiteit van het uitvoeren van veelvoorkomende handelingen;
  • onduidelijkheid over transacties en het waarborgen van consistentie.

Bij ieder van de bovenstaande zaken zijn ‘reparatie-acties’ te bedenken: oplossingen die snel te realiseren zijn en op korte termijn de ergste nood lenigen. Gemeenten en marktpartijen zijn hier – logischerwijs – ook mee bezig. Maar we willen voorkomen dat we, in de haast om zaken werkend te krijgen, te kort door de bocht gaan. Dus niet later concluderen dat een gekozen oplossing toch ongewenste neveneffecten met zich mee blijkt te brengen, of alleen in één specifieke situatie toepasbaar is. We zoeken kortom duurzame, herbruikbare oplossingen bij de gevonden problemen. We gaan daartoe:

  • goed luisteren naar gemeenten en marktpartijen om te horen waar ze tegenaan lopen en wat er volgens hen nodig is om dat op te lossen;
  • op basis daarvan de Common Ground doelarchitectuur verder uitwerken, te beginnen daar waar die raakt aan bovengenoemde problemen;
  • beschrijven welke patronen er zijn om de huidige en toekomstige uitdagingen bij gedistribueerde gegevensopslag aan te kunnen gaan;
  • samen met gemeenten en leveranciers hierin keuzes maken.

Tijdens deze activiteiten willen we een aantal vragen beantwoorden, waaronder:

  • welke soorten API’s onderscheiden we, en waarvoor worden deze gebruikt?ontwerpen we API’s taak- of data-gericht (of, afhankelijk van omstandigheden allebei)?
  • wat is de gewenste omvang of granulariteit van een API of resource?
  • welke interactiepatronen voor compositie van API’s of orkestratie en choreografie van services kunnen we onderscheiden?
  • hoe richten we (als vervolg op de bevindingen van eerder dit jaar) modern Identity en Acces Management in een API-landschap in?

Inhoud[bewerken]

Eerste stappen: veilig en transparant werken met API's[bewerken]

Eerder is gewerkt aan oplossingspatronen voor Identity en Access Management in een API-landschap. De resultaten hiervan zijn te vinden op GitHub.

Vervolg: ARA[bewerken]

De API-referentiearchitectuur (ARA) moet niet alleen gaan beschrijven hoe gemeenten binnen hun informatievoorziening gebruik kunnen maken van API's, maar ook welke uitgangspunten en principes ontwerpers van API-standaarden (zoals de VNG) zouden kunnen hanteren bij het ontwerpen daarvan.

Omdat deze uitgangspunten en principes van invloed zijn op bijvoorbeeld de performance die van een API verwacht kan worden, zijn deze niet alleen belangrijk voor API-ontwerpers, maar ook voor gemeenten en hun leveranciers die ze immers moeten implementeren.

Eerste resultaten[bewerken]

De eerste onderdelen van ARA zijn ondertussen opgeleverd. Het gaat hierbij om een bird's eye view waarin enkele (kern) concepten worden geduid waarmee bij het ontwerp van API's en API-standaarden rekening gehouden moet worden, en een verkenning naar de implicaties van distributie van gegevens over meerdere API's waar die gegevens in samenhang worden bevraagd of in één transactie worden vastgelegd. Deze resultaten zijn gebundeld in een powerpointpresentatie.

Bijeenkomst met gemeenten en leveranciers[bewerken]

Naar aanleiding van internationale ‘best practices’ en bijbehorende voor- en nadelen hebben we aan gemeenten en leveranciers een aantal stellingen voorgelegd die te maken hebben met fundamentele keuzes die we moeten maken om te komen tot een coherent API-landschap te komen. Hoe denken we bijvoorbeeld over convenience API’s en gedeelde databases? Hebben we daarbij een gezamenlijke voorkeur?

Vervolgens werd gekeken naar onderwerpen die volgens de aanwezigen verdere uitwerking verdienen. Daarbij werd aan de volgende thema’s prioriteit gegeven: het stap-voor-stap uitwerken van een API Referentie Architectuur (ARA), domeinafbakening en een verder uitgewerkte oplossing voor autorisaties waarbij onze API-standaarden aansluiten.

Over deze bijeenkomst hebben we een blog geschreven, die te lezen is op de Common Ground-website.