URL translatie. Gedrag van de API bij gebruik door applicaties buiten de eigen infrastructuur van een gemeente (saas applicaties)

[RvdKlip]

Omdat applicaties in een server buiten Rotterdam gehost worden en de ZGWAPI's binnen het Rotterdamse netwerk draaien is er een ESB/Gateway (Opentunnel) gemaakt zodat we van buiten Rotterdam naar interne servers (OpenZaak) kunnen.

In de ZgwApi wordt veel gebruik gemaakt van URL's. Alle losse stukjes (zaaktype, zaak, status etc.) worden geïdentificeerd door en verwijzen naar elkaar op basis van URL's. Deze URL's zijn onderdeel van de REST berichten en zijn rechtstreeks te benaderen. In sommige calls geeft je de URL's mee als query parameters (?zaak=https://etc). Doordat er een ESB/gateway (Opentunnel, NLx?, etc.) tussen zit, zijn de URL's niet meer direct te benaderen. De URL's moeten nu vertaald worden. Door de ESB krijgen de entiteiten andere URL’s.

We kunnen kennis van dit probleem neerleggen in de client toepassing. Voordeel is dat de URL’s naar de bron registraties origineel blijven. Nadeel is dat je kennis van de ESB in een client applicatie legt (statisch, dus onderhoudsgevoelig). Een client applicatie die meerdere bronnen bevraagt bij meerdere gemeenten moet logica van deze gemeenten bijhouden. Doe je de vertaling van de URL’s in de ESB dan is er geen kennis nodig in de client applicatie van het bestaan van een ESB. Echter wordt de ESB nu een soort afgeleide registratie en zal kennis bij moeten houden welke URL’s er vertaald zijn om deze in de toekomst ook nog te kunnen beantwoorden.

Voorbeeld Zaaktype URL OpenZaak: https://openzaak-open-zaak.apps.ocp.rotterdam.nl/catalogi/api/v1/zaaktypen/1a986ed0-d91d-4581-88c9-e4caccb7712d Opentunnel: https://xmlgw.preprod.rotterdam.nl/opentunnel/rad/openzaak/ocp/catalogi/api/v1/zaaktypen/1a986ed0-d91d-4581-88c9-e4caccb7712d

Welk patroon wordt vanuit architectuur VNG geadviseerd voor gebruik van de ZGW API's?

[michielverhoef]

@hdksi Eenzelfde probleem speelde ook in Tilburg bij hun zaakbevragingen oplossing in een ESB. Ik kan me voorstellen dat dit vaker gaat optreden. Dit heeft niet zozeer met de API's te maken als met de toepassing er van.

[hdksi]

Ik geloof niet dat we voor dit specifieke probleem een bestaand advies hebben, maar zal eens rondvragen. Voor de vuist weg zou ik zeggen dat je dit issue omwille van beheer(s)baarheid niet ergens anders dan in de ESB zelf moet willen oplossen. Maar dat kan ook komen omdat ik helemaal begrijp waarom de ESB in dat geval een soort 'afgeleide registratie' wordt.

Misschien zijn hier mensen met échte ervaring? @CMasselink of @VerbeekIT bijvoorbeeld?

[CMasselink]

Wij hebben als uitgangspunt dat we zoveel mogelijk API's via NLX ontsluiten, dus ook de ZGW API's. Dan wordt de vertaling naar de achterliggende service al in de directory opgelost. Je moet dan wel echt heel consequent zijn in het toepassen van NLX (bijvoorbeeld ook voor een zaaktype altijd naar NLX verwijzen).... Er kan in de zaak uiteraard ook weer naar resources verwezen worden die niet via NLX te ontsluiten zijn en dan houd je het probleem....

Wat betreft ESB's: die worden vaak als "centraal ontkoppelpunt" ingezet zodat taakapplicaties niet allerlei URL vertalingen bij hoeven te houden. Het lijkt me daarom niet heel gek om vertalingen in een ESB/gateway bij te houden. Ook omdat je anders in taakapplicaties en registraties (met terugwerkende kracht) allerlei URL's moet gaan aanpassen als er ergens een keer een hostname verandert.

Het is sowieso verstandig om zoveel mogelijk eigen domeinnamen te gebruiken die redelijk stabiel kunnen blijven. Ook bij SaaS applicaties. Wij eisen bijvoorbeeld bij SaaS applicaties dat we wel onze eigen domeinnamen kunnen gebruiken. Dan hoeven we geen leverancier specifieke URL's te gebruiken. Als je dan een keer van leverancier verandert, kan je de URL gelijk houden.

Wel een interessant vraagstuk, helemaal voor de lange termijn. In een gedistribueerd landschap moeten de resources natuurlijk wel beschikbaar blijven... Ik ben ook benieuwd hoe andere gemeenten / organisaties hier mee omgaan.

[sergei-maertens]

Dan wordt de vertaling naar de achterliggende service al in de directory opgelost

dat is niet helemaal waar - een zaak vraag je op via de URL van de outway met NLX, en elke organisatie heeft een andere outway URL. De provider kant kan je niet URLs terug geven die specifiek op jouw outway matchen.

Ik hanteer hier zelf graag het concept van "canonical URLs" en dat zijn de hostnamen/domeinen die in de API berichten voor komen. Het is aan de consumer (of ESB) om dat te vertalen naar iets wat voor de consumer benaderbaar is, en dat gebeurt op request EN response niveau. Niet ideaal...

Op lange termijn en als domeinnamen veranderen moet dit m.i. met de standaard HTTP mechanismen opgelost worden: HTTP 301 en HTTP 302 redirects. Deze dienen naar de nieuwe locatie te verwijzen en zij technisch vrij eenvoudig in te richten op webserver-niveau.

[CMasselink]

dat is niet helemaal waar - een zaak vraag je op via de URL van de outway met NLX, en elke organisatie heeft een andere outway URL. De provider kant kan je niet URLs terug geven die specifiek op jouw outway matchen.

Ja eens dat bedacht ik later ook. Daar lopen we ook al tegenaan omdat we meerdere outways gaan krijgen. Resources krijgen volgens mij dan al verschillende URLS (neem een zaaktype verwijzing die via 2 verschillende outways worden vastgelegd).

[joeribekker]

Getriggered door een mail van Michiel lees ik deze thread weer eens en zet wat gedachten neer:

Hoewel ik puristisch nog steeds graag URI's gebruik (dus: niet persé bereikbare/geldige resources - het is een identifier) wordt dit in de praktijk heel vaak gezien als URL's (dus: wel bereikbare/geldige resources, mits autorisatie e.d. - het is een locator). Ook ik vind URL's overigens erg fijn. En ja, je kan een URL in een URI-veld stoppen.

URN's (names) kan deze verwarring te voorkomen. Een mapping tabel is dan wel altijd nodig maar in Open Zaak hebben we dat ook eigenlijk al omdat we van elke service ook credentials moeten hebben. Volgens mij werden er in het cloud profiel voor notificaties ook URN's gebruikt? Weet het niet zeker meer.

urn:nl:zaken:<rsin>:<zaaknummer> o.i.d. We zouden alle waarden al moeten hebben om deze te genereren. Maar ja, gaan we dan een status (wat een zelfstandige resource is) ook een URN geven? In notificaties onderkennen we een hoofdobject zoals "zaak" en de rest zijn (sub)objecten, zoals "status" en "zaakobjecten".

FSC (NLX) doet het, als we localhost wegdenken, eigenlijk ook wel aardig door een unieke organisatie/service naam-koppel te gebruiken, en daarna de relatieve URL.

Dit abstraheert allemaal weg van (absolute) URLs (wat het probleem zou moeten tackelen van gateway's/proxies/esb's) en een mapping tabel is in alle scenario's nodig. Afhankelijk van of je extern of intern bent, ziet enkel de mapping tabel er anders uit.

[sergei-maertens]

Het probleem blijft dat distributed systems met URNs niet werken, tenzij je voor elk (zaaknummber + bronorganisatie) combinatie gaat vastleggen welke service die aanbiedt.

Als applicatie X de zaken API zelf implementeert, en de organisatie maakt ook gebruik van Open Zaak bijvoorbeeld, dan heb je 2 bronnen waar zaken staan. Dat is nu met URLs opgelost - die bevat namelijk de informatie in welke bron je de gegevens moet ophalen zonder over alle bronnen heen te scannen. Dan heb ik ook nog niet gedacht over datamigraties waarbij gegevens misschien toch van ene applicatie naar andere overgezet worden... 🤔

Ik wil graag URNs gebruiken, maar laat ons ook vooral niet de cases vergeten precies waarom er voor URLs gekozen was.

[HenkVanMaanen]

@joeribekker

FSC (NLX) doet het, als we localhost wegdenken, eigenlijk ook wel aardig door een unieke organisatie/service naam-koppel te gebruiken, en daarna de relatieve URL.

De url constructie http(s)://outwayadres/serienummer/service-naam is veranderd in de nieuwe FSC standaard. Het idee nu is om de organisatie / service naam combinatie mee te sturen in een header ipv in de url. De url wordt dan http(s)://outway/, icm de header weet de outway dan naar welke organisatie en service hij de request moet sturen. Dit opent de deur naar gRPC over FSC. Zie https://commonground.gitlab.io/standards/fsc/core/draft-fsc-core-00.html#name-routing

[PvdZijden]

Om een spreekwoordelijk duit in het zakje te doen, sorry voor het wakker schudden overigens. Ik snap waarschijnlijk door een gebrek aan kennis niet goed waarom een volledige URL gebruikt wordt en niet een context-URI, en desnoods een host (als concessie) los van elkaar bijvoorbeeld.

Op hybride en 'grotere' infrastructuur is er absoluut een noodzaak voor de inzet van een (relatief klassiek) gateway patroon, API's die in hun payload dergelijke infrastructurele informatie als een volledige URL vermelden zijn een overbodig probleem en wat mij betreft in strijd met het ontkoppelen. Ik snap dat er een voordeel zit voor die situaties waarin je met meerdere zakenmagazijnen van doen hebt (kort door de bocht omschreven) omdat de 'afnemer' een gegeven voor handen heeft wat aangeeft waar de zaak 'leeft', maar dat is alleen wanneer die dus al weet van het bestaan van de zaak, en die informatie nog klopt wanneer het gebruikt wordt.

Voor afnemers die een zaak zoeken (en niks anders weten dan dat er meer dan één endpoint voor zaakinformatie is) los je niks op, en zal je nog steeds alle magazijnen/registers moeten bevragen vanuit de afnemer. Een oplossing die dergelijke zoekacties faciliteert voor afnemers en slim werkt met caching is volgens mij meer dan voldoende schaalbaar te maken, en als je ook nog iets zoals sharding toepasbaar maakt (op technische/data logica of informatiekundige-context of iets dergelijks) kan je helemaal los gaan denk ik.

Wat er nu gebeurt is dat er dus feitelijk door een gateway/integratie-infra component een search & replace op de gehele payload gedaan wordt, of op zijn minst op de elementen met mogelijke URLs (en die laatste optie maakt het weer minder flexibel enz). Evengoed begrijp ik dat het doorvoeren van een dergelijke verandering op dit punt, in een standaard zoals deze, eveneens een aanzienlijke impact kan hebben (op zichzelf ook een teken van oneigenlijke/impliciete koppeling misschien). Hoe dan ook zou ik persoonlijk de URL graag zien vertrekken uit payloads van APIs.