Toevoeging async request-response patroon

[terborg]

Bij deze een voorstel voor toevoeging van het asynchrone async request-respons patroon.

[terborg]

@TimvdLippe zou jij hier ook een review van willen doen?

[TimvdLippe]

Dit lijkt mij een valide architectuurpatroon. Of we dit voor de gehele overheid willen gaan toepassen is een tweede, maar dat het in ieder geval als artikel op de kennisbank staat lijkt mij nuttig. Dus +1 van mijn kant.

Het lijkt me wel handig dat, als dit inderdaad voor veel organisaties nuttig is, dat we de afspraken dan wel vastleggen in een ADR module. Dan zorgen we ervoor dat namen zoals "Location" en "Idempotency-Key" consistent zijn.

[Copilot]

Pull request overview

Deze PR voegt documentatie toe voor het Asynchronous Request-Reply patroon binnen de architectuursectie, bedoeld om langdurige/ onvoorspelbare operaties asynchroon af te handelen met een status-endpoint.

Changes:

• Nieuwe architectuurpagina toegevoegd die uitlegt wanneer en hoe async request-reply toe te passen (incl. polling/SSE/webhooks).
• Mermaid sequentiediagram toegevoegd voor de polling-variant.
• OpenAPI-voorbeeld toegevoegd met 202 Accepted + Location header en een statusresource.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[terborg]

Hoi @joepio, zou jij hier ook nog een review van willen doen?

[tomootes]

@dvh we hebben hier een approved review van @TimvdLippe. Ben jij het verder eens? Dan kunnen we hem mergen wmb.

[dvh]

@joostfarla @TimvdLippe @Fdeutekom is dit niet waar de KPA Werkgroep Notificaties mee bezig is?

[terborg]

@dvh is het een idee om een concrete use case onderaan het document toe te voegen? Ik zit te denken aan een asynchrone out-of-band bestandsupload. Daarnaast zouden we dit soort documenten al kunnen voorzien van spectal linting rules en misschien kleine mini referentie-implementaties, zodat latere adoptie al testbaar zou kunnen zijn.

[dvh]

@terborg zeker goede ideeën, alleen wordt hier as we speak over nagedacht in een speciale werkgroep van het Kennisplatform API's, alwaar deze regels opgesteld worden. Als hier concrete voorstellen uitkomen gaan ze naar Logius voor de volgende consultatieversie van de API Design Rules, alwaar de spectral rules worden opgesteld.

Nu willen wij best vooruit lopen op de standaard (doen we bijv. ook met problem+json errors) maar dan moeten we wel weten dat dit ook in lijn is met wat er hoogstwaarschijnlijk uit gaat komen. Tenzij het niet eens op de radar staat, want dan duurt het te lang.

[terborg]

Nu willen wij best vooruit lopen op de standaard (doen we bijv. ook met problem+json errors) maar dan moeten we wel weten dat dit ook in lijn is met wat er hoogstwaarschijnlijk uit gaat komen. Tenzij het niet eens op de radar staat, want dan duurt het te lang.

Mooi. Dit soort PR's werken wel goed voor consensusvorming ook, hoe meer reviews hoe beter.

[terborg]

Ha @joeribekker zou jij hier misschien ook een review van willen doen?

[joeribekker]

Conceptueel prima patroon dat we regelmatig toepassen in APIs. In de meeste gevallen gaat het daarbij overigens om exports/rapportages genereren (geen data wijzigende acties). We gebruiken hier ook POSTs voor omdat we het als "acties" zien.

Het wijkt af van hoe bij ZGW APIs grote bestanden worden geupload maar waar dit patroon uitgaat van een langdurige verwerking is een grote bestandsupload een langdurige connectie + verwerking.

Verder ben ik altijd van eerst beproeven, daarna opnemen in de standaard maar als concept standaard prima.

[TimvdLippe]

Naar mijn weten wordt er binnen de werkgroep Architectuur Notificeren niet specifiek aan dit vraagstuk gewerkt. Zowel notificeren als het patroon zoals hier beschreven zijn asynchroon, dat komt inderdaad overeen. Maar de werkgroep focust op notificeren in de context van registraties en events. Het patroon hier gaat om een request-response patroon wat meer lijkt op een message.

Ook lijkt het mij handig om de status van zulke kennisartikelen duidelijk te maken. Naar mijn weten zijn kennisbank artikelen niet normatief en ook niet per definitie de autoriteit. Het zijn informatieve artikelen hoe je dingen handig aan kan pakken en niet meer dan dat. In dat kader vind ik dit artikel passen.

Als er dan wordt gekeken of dit artikel mogelijk in strijd is met toekomstige output van een werkgroep, dan is mijn inschatting dat dat hier niet het geval is. Daarom stel ik voor dat we dit artikel als informatief publiceren, mogelijk ook met die kanttekening erbij. En als in de toekomst blijkt dat dit patroon wel/niet werkt, dan kunnen we daar in de standaard iets over opschrijven.

TLDR: Lijkt mij een nuttig informatief artikel die waarschijnlijk niet in conflict is met mogelijke toekomstige output van de werkgroep Notificeren.

[terborg]

Het wijkt af van hoe bij ZGW APIs grote bestanden worden geupload maar waar dit patroon uitgaat van een langdurige verwerking is een grote bestandsupload een langdurige connectie + verwerking.

Hoeft niet per se -- denk aan een out-of-band upload. De langdurige (upload) operatie is dan geen concern meer van de primaire call, maar van een secundaire. Voor de primaire call is het een kwestie van wachten op completion van de secundaire. In geval van zo'n bestandsupload zou de primaire (async) call de presigned url teruggeven, waarna de upload via die presigned url verloopt. Het upload-concern is dan gedelegeerd.

[joeribekker]

Hoeft niet per se -- denk aan een out-of-band upload.

Dat is het ook :) Een POST op EIO, geeft een endpoint terug. Vervolgens bestand uploaden op dat endpoint. Maar het is dus niet exact wat in het patroon (sequence diagram) staat, dat was vooral mijn punt.

[terborg]

Hoeft niet per se -- denk aan een out-of-band upload.

Dat is het ook :) Een POST op EIO, geeft een endpoint terug. Vervolgens bestand uploaden op dat endpoint. Maar het is dus niet exact wat in het patroon (sequence diagram) staat, dat was vooral mijn punt.

Top, iets om te verbeteren / aan te passen. Ik werk het verder uit.