Namens de technische werkgroep van de OpenAPI specificatie willen we graag onderstaande voorstel doen.
Aanleiding
Niet alle partijen zijn voornemens om middels een synchrone response aan te kunnen geven of het ontvangen bericht succesvol is verwerkt. Redenen hiervoor zijn bijvoorbeeld het niet real-time kunnen verwerken van een bericht of afhankelijk te zijn van een niet-real-time / STP proces. Hierdoor is een noodzaak ontstaan om een response schema op te stellen waarmee asynchroon een terugkoppeling gegeven kan worden aan de partij die initieel een bericht heeft verstuurd.
Feedback schema
Het volgende schema wordt voorgesteld om middels een asynchrone reponse de initiële verzending van een bericht van feedback te voorzien. Onder feedback verstaan we het terugkoppelen of:
Het bericht is geaccepteerd
Het bericht is afgewezen
Indien afgewezen, dan moet 1 van de volgende redenen worden opgegeven:
Zoeksleutel onbekend
Technische fout
Inhoudelijke fout
Volgordelijke fout
Data zender en ontvanger matchen niet
Overig
Het is altijd noodzakelijk om een verklaring bij de afwijsreden mee te geven.
Asynchrone response
Wanneer een partij het bericht niet real-time kan verwerken, en dus geen inhoudelijke synchrone repons kan terug geven aan de verzender van het bericht, dan is het noodzakelijk dat de ontvanger in eerste instantie synchroonhttp-code 202 terug geeft, wat de initiële verzender van het bericht laat weten dat er nog een asynchroon antwoord zal volgen.
Synchrone respons
Vanuit de technische werkgroep willen wij tevens voorstellen om het feedback schema te hanteren bij het geven van een inhoudelijke synchrone respons, in het geval er sprake is van een foutsituatie bij het synchroon verwerken van een bericht. Dit is het geval bij http-code 400 (bad request). Hierdoor wordt het gebruik van de error-entiteit overbodig in de request body van de aanroepende partij.
Aanpassingen huidige schema's (Berichtstructuur 1 t/m 14)
Door gebruik te maken van een feedback schema voor zowel de synchrone als asynchrone respons waarin de foutsituatie wordt beschreven, wordt de entiteit 'error' in de huidige berichtstructuren overbodig:
We willen daarom graag voorstellen om de error entiteit te verwijderen uit deze json-schemas.
Nieuw endoint
Met het introduceren van een feedback schema is voor het gebruik in een asynchrone situatie een nieuw endpoint noodzakelijk. Dit endpoint zullen we 'feedback' gaan noemen en nemen wij op in de 1.0.8 versie van de OpenAPI specificatie.
dma61
commented
6 months ago
Beste Duco,
Namens de technische werkgroep van de OpenAPI specificatie willen we graag onderstaande voorstel doen.
Aanleiding Niet alle partijen zijn voornemens om middels een synchrone response aan te kunnen geven of het ontvangen bericht succesvol is verwerkt. Redenen hiervoor zijn bijvoorbeeld het niet real-time kunnen verwerken van een bericht of afhankelijk te zijn van een niet-real-time / STP proces. Hierdoor is een noodzaak ontstaan om een response schema op te stellen waarmee asynchroon een terugkoppeling gegeven kan worden aan de partij die initieel een bericht heeft verstuurd.
Feedback schema Het volgende schema wordt voorgesteld om middels een asynchrone reponse de initiële verzending van een bericht van feedback te voorzien. Onder feedback verstaan we het terugkoppelen of:
Indien afgewezen, dan moet 1 van de volgende redenen worden opgegeven:
Het is altijd noodzakelijk om een verklaring bij de afwijsreden mee te geven.
Asynchrone response Wanneer een partij het bericht niet real-time kan verwerken, en dus geen inhoudelijke synchrone repons kan terug geven aan de verzender van het bericht, dan is het noodzakelijk dat de ontvanger in eerste instantie synchroon http-code 202 terug geeft, wat de initiële verzender van het bericht laat weten dat er nog een asynchroon antwoord zal volgen.
Synchrone respons Vanuit de technische werkgroep willen wij tevens voorstellen om het feedback schema te hanteren bij het geven van een inhoudelijke synchrone respons, in het geval er sprake is van een foutsituatie bij het synchroon verwerken van een bericht. Dit is het geval bij http-code 400 (bad request). Hierdoor wordt het gebruik van de error-entiteit overbodig in de request body van de aanroepende partij.
Aanpassingen huidige schema's (Berichtstructuur 1 t/m 14) Door gebruik te maken van een feedback schema voor zowel de synchrone als asynchrone respons waarin de foutsituatie wordt beschreven, wordt de entiteit 'error' in de huidige berichtstructuren overbodig:
We willen daarom graag voorstellen om de error entiteit te verwijderen uit deze json-schemas.
Nieuw endoint Met het introduceren van een feedback schema is voor het gebruik in een asynchrone situatie een nieuw endpoint noodzakelijk. Dit endpoint zullen we 'feedback' gaan noemen en nemen wij op in de 1.0.8 versie van de OpenAPI specificatie.