Op naar een API Referentie Architectuur (ARA): knippen en plakken

‘Typen’ API’s

Wat hebben we ondertussen aan ‘nieuwe’ gedachten opgedaan? Vandaag duiken we de inhoud in en delen we kort onze eerste bevindingen. Daarvoor om te beginnen een korte terugblik op de eerste verdiepende ARA-bijeenkomst met gemeenten en marktpartijen. Toen stonden verschillende ‘soorten’ of ‘typen’ API’s die we binnen de gemeentelijke informatievoorziening tegenkomen centraal.

Het maken van een onderscheid naar type of soort is nuttig omdat bijvoorbeeld API’s die een set gegevens afkomstig uit een ‘bron’ beschikbaar stellen andere kenmerken hebben dan API’s waarin gegevens uit meerdere bronnen samenkomen. Binnen de laatste categorie kunnen vraagstukken rondom gedistribueerde query’s en mogelijk zelfs transacties een rol spelen. Als het hierom gaat lijkt “voorkomen is beter dan genezen” het meest voor hand liggende adagium.

Domeinen en samenhang

Voorkomen betekent: zet niet de schaar in gegevensverzamelingen die ‘bij elkaar horen’. Maar het gebruik van het vage begrippen als ‘bij elkaar horen’ en ‘bron’ geeft al aan dat het ontbreekt aan een vocabulaire dat beschrijft waar sprake is van samenhang en waar juist duidelijk een grens overschreden wordt. Niet verwonderlijk dus dat deelnemers vroegen om meer aandacht voor het onderwerp ‘domeinafbakening’ in relatie tot API-ontwerp.

Maar dat begrip ‘domein’ is lastig. Hoe een domein eruit ziet is afhankelijk van het perspectief. Een medewerker van het klantcontactcentrum, die afhankelijk is van informatie over zaken voor het beantwoorden van vragen van inwoners, zal daaraan binnen ‘haar domein’ een andere status toekennen – die leidt tot andere wensen over samenhang – dan een medewerker die omgevingsvergunningen behandelt. Het ontwerp van een API(-standaard) moet dus altijd beginnen met een passende informatieanalyse, waarbij aandacht voor gebruikerswensen van verschillende belanghebbenden belangrijk zijn.

Knippen en plakken

Hoe proces en resultaat van een informatieanalyse eruit zien, is noodzakelijkerwijs afhankelijk van het domein dat bekeken wordt en het doel van de analyse. In algemene zin kunnen we daarbij slechts beperkt handvatten bieden. Wel kunnen we een aantal overwegingen geven die op basis van de uitkomst van zo’n analyse kunnen helpen te waar sprake is van sterke samenhang tussen gegevens, en waar zich tussen gegevenssets een duidelijke grens aftekent en (dus) geknipt kan worden. ‘Knipindicatoren’ zijn:

1. Het eigenaarschap of de beheerverantwoordelijkheid van een deel van de gegevens ligt bij en andere eigenaar of organisatie(onderdeel);
2. Het karakter van een deel van de gegevensverzameling maakt het gebruik van een verschillende opslagtechnologieën voor de hand liggend. Denk hierbij aan een zaakdossier dat bestaat uit gestructureerde relationele gegevens en ongestructureerde bestanden.
3. Een deel van de gegevensset beschrijft een concept dat ook buiten het onderzochte domein herkend wordt en dus wellicht te generaliseren is. Denk aan de zaak die in feite een generalisatie is van heel uiteenlopende processen die op verschillende plaatsen in de gemeente worden uitgevoerd.
4. De samenhangende gegevensset wordt dusdanig omvangrijk dat eenvoudige vervanging van een oplossing voor opslag daarvan onmogelijk wordt. Dit is de meest vage indicator. Echter is het belangrijk in het oog te houden dat niet knippen weliswaar netwerkbelasting vermindert of gedistribueerde query’s en transacties vermijdt, maar op andere fronten nieuwe uitdagingen met zich mee kan brengen.

Indicatoren om niet te knippen (ofwel te plakken 😉) zijn:

1. Uit informatieanalyse blijkt grote samenhang tussen gegevens (bijvoorbeeld bij hoofd- en subobjecttypen of n:m relaties)
2. Gegevens hebben ‘los’ geen enkel bestaansrecht en zijn niet te generaliseren voor gebruik in andere domeinen.
3. Er is een groot belang bij het snel en met waarborgen voor de integriteit van de gegevensset kunnen bewerken van gegevens.
4. Er is een groot belang bij het snel en met waarborgen voor de integriteit van de gegevensset kunnen opvragen van gegevens.

Registers

Vanwege het eerdergenoemde gebrek aan vocabulaire is het zinvol te kijken of we een set gegevens waarin niet geknipt is kunnen beschrijven. We hanteren daarvoor een bekend (GEMMA-)begrip: het register. Dit definiëren we in concept als “een component in het applicatielandschap die een samenhangend geheel van gegevensverzamelingen beschikbaar stelt.” Belangrijker dan deze definitie zijn de verwachtingen die horen bij interacties binnen de grenzen van een register: daarbij worden goede performance en waarborgen voor consistentie verwacht. Is er sprake van interacties waarbij gegevens uit meerdere registers betrokken zijn, moet juist rekening gehouden worden met beperkte(r) performance en het zelf organiseren van consistentiewaarborgen.

Verdiepende bijeenkomst

Deze en andere inzichten hebben we begin februari in een tweede verdiepende bijeenkomst aan gemeenten en leveranciers voorgelegd. Om daarbij voorkennis en standpunten over bestaande domeinen te vermijden, deden we dit aan de hand van een fictief nieuw gemeentelijk domein. Van dit domein hebben we de grenzen bepaald, die we vervolgens aan de hand van verschillende, steeds complexer user story’s hebben beproefd. Dit leverde mooie discussies op met een aantal ‘parkeerpunten’ als historische bevragingen, voorzieningen voor business intelligence. Ook werd duidelijk dat de betekenis van woorden als ‘bron’, ‘dupliceren’ en ‘cachen’ nader beschrijving verdient.

Vooruitblik: wat gaan we doen?

De tijdens deze bijeenkomst opgedane inzichten gaan we beproeven in de API-architectuur voor het klantinteracties-domein. Hiermee zetten we een eerste stap op weg naar te standaardiseren API's voor Klantinteracties. Parallel daaraan bereiden we als onderdeel van de ontwikkeling van ARA een nieuwe verdiepende bijeenkomst voor.

Blijf op de hoogte!

Wil je op de hoogte blijven houd dan de blogs op commonground.nl in de gaten. Op LinkedIn wordt de blog ‘gepusht’. Stuur Mascha een connectieverzoek om regelmatig updates over dit onderwerp te ontvangen. Zodra er weer een Common Ground-Fieldlab wordt georganiseerd zullen we deelnemen aan het programma om de stand van zaken in begrijpelijke taal terug te koppelen.

Auteurs: Ivo Hendriks (Architect Kenniscentrum Architectuur, Ivo.Hendriks@vng.nl) en Mascha Kranse (Coördinator Kenniscentrum Architectuur, Mascha.Kranse@vng.nl).