ZGW-API’s koppelen aan uw eigen applicatie

De ZGW-API’s zijn de standaard-API’s voor zaakgericht werken van VNG Realisatie, ontwikkeld binnen Common Ground. Zij vervangen de oudere, op SOAP gebaseerde koppelvlakken door een samenhangende set REST-API’s: de Zaken API voor zaken, de Documenten API voor documenten, de Catalogi API voor zaaktypen, de Besluiten API voor besluiten en de Notificaties API voor gebeurtenissen. Autorisatie loopt via een eigen API.

Elke API bestaat uit een Open API-specificatie, technische documentatie over het gedrag tijdens gebruik en een of meer datamodellen. Die specificatie is samen met de documentatie normatief. Dat is prettig precies en het betekent ook dat een implementatie die alleen de specificatie volgt, nog steeds fout kan zijn op het gedrag.

De volgorde waarin u de onderdelen nodig heeft, is bijna altijd dezelfde en zelden de volgorde waarin u begint.

• Autorisaties: welke applicatie mag wat, per API en per zaaktype.
• Catalogi: welk zaaktype, welke statustypen, welke resultaattypen bestaan er.
• Zaken: aanmaken, statussen doorlopen en betrokkenen vastleggen.
• Documenten: bestanden koppelen aan een zaak, met de juiste vertrouwelijkheid.
• Besluiten: het besluit dat uit de zaak volgt, apart van de zaak zelf.
• Notificaties: op de hoogte blijven van wijzigingen zonder te blijven pollen.

De meeste implementaties beginnen bij de Zaken API, omdat dat de kern lijkt. In de praktijk loopt dat binnen een dag vast op de vraag welk zaaktype u eigenlijk aanmaakt en welke statussen daarbij horen. Die informatie staat in de Catalogi API, en zij verschilt per gemeente.

Dat laatste is het punt dat leveranciers onderschat. De standaard is gelijk, de inrichting niet: zaaktypen, statustypen en resultaattypen worden per organisatie vastgesteld. Een koppeling die zaaktypen hardcodeert, werkt bij één gemeente en breekt bij de volgende.

Wij bouwen de koppeling daarom vanaf de catalogus. Uw applicatie haalt op wat er bestaat en werkt daarmee, in plaats van uit te gaan van wat er bij de eerste gemeente toevallig stond.

Het tweede punt waarop implementaties vastlopen, is actualiteit. Een applicatie die elke paar minuten de Zaken API bevraagt om te zien of er iets is veranderd, belast de omgeving en loopt toch achter.

Er komt bij dat bevragen niet alleen traag is maar ook incompleet. Een zaak die wordt aangemaakt en binnen een minuut weer wordt gewijzigd, ziet u bij een interval van vijf minuten als één gebeurtenis. Voor een overzichtsscherm maakt dat weinig uit; voor een proces dat op een statuswijziging moet reageren, is het het verschil tussen werken en niet werken.

De Notificaties API is daarvoor bedoeld: u abonneert zich op gebeurtenissen en krijgt bericht. Dat vraagt aan uw kant een ontvangstpunt dat altijd bereikbaar is en dat een bericht dat twee keer binnenkomt netjes afhandelt. Dat is een ontwerpkeuze die u vooraf maakt, niet iets dat u er later bij bouwt.

Aan de gemeentekant staat een implementatie van de standaard, van een leverancier of als open-source component. Aan uw kant staat uw eigen applicatie. Wij bouwen daartussen een laag die de catalogus uitleest, de autorisaties afhandelt en de gebeurtenissen ontvangt.

Werkt u met meerdere gemeenten, dan is die laag ook de plek waar de verschillen in inrichting landen. Voor bredere gegevensstromen sluit dit aan op data-integratie software. Hoe koppelingen in het algemeen werken staat op systemen koppelen met een api.

Let op de versies. De API’s ontwikkelen door en niet elke gemeente draait dezelfde versie. Vraag vooraf welke versies van de Zaken-, Documenten- en Catalogi-API draaien en houd er rekening mee dat die per omgeving verschillen, ook binnen dezelfde organisatie tussen test en productie.

Let ook op de autorisaties. Rechten worden per applicatie en vaak per zaaktype toegekend, en een ontbrekend recht geeft een foutmelding die niet altijd verraadt dat het om autorisatie gaat. Vraag vroeg om een testomgeving met representatieve rechten; zonder dat bouwt u tegen een omgeving waarin alles mag.

Het aantal API’s dat u werkelijk raakt, bepaalt het meeste. Alleen zaken lezen is aanzienlijk kleiner dan zaken aanmaken met documenten en besluiten, omdat u dan ook met de catalogus en de vertrouwelijkheidsniveaus te maken krijgt.

Daarnaast telt het aantal organisaties. Eén gemeente is een koppeling; vijf gemeenten is een koppeling plus een laag die de verschillen in inrichting opvangt, en die laag is het werk dat u vooraf wilt inschatten.

1. We vragen de versies en een testomgeving op, met rechten die op productie lijken.
2. We beginnen bij de Catalogi API en halen zaaktypen en statustypen op.
3. We bouwen de eerste stroom, meestal zaken lezen en tonen in uw eigen applicatie.
4. Daarna schrijven: aanmaken, status doorzetten en documenten koppelen.
5. Pas als dat staat, sluiten we op notificaties aan in plaats van te blijven bevragen.

• Data-integratie software
• Systemen koppelen met een api
• Alle software op maat