Opnemen gerelateerde informatie in antwoord

[michielverhoef]

Naar aanleiding van de wens om het aantal calls te verminderen en gerelateerde informatie op te nemen in een antwoordbericht.

Uitgangspunt is vooralsnog alleen informatie uit hetzelfde domein io te nemen. Normaal gesproken is dat dezelfde API. Bij Zaakgericht werken wordt informatie uit de Catalogi API (bv Zaaktypen, EnkelvoudigInformatieobjecttypen etc.) ook meegenomen in de Zaken API en Documenten API.

Tijdens de bijeenkomst van de technische gebruikersgroep is een aantal oplossingsrichtingen gepresenteerd. In dit issue worden de voor- en nadelen tegen elkaar afgezet.

Inclusions
VNG-Realisatie/gemma-zaken#1960 (comment)

Voordelen:

• Shape van resultaat blijft hetzelfde -> backwards compatible
• namespace voor cross-api referentie. Bv documenten.enkelvoudiginformatieobject of catalogi.zaaktype
• In de API is aan te geven welke API versie ondersteund wordt
• Voorspelbaar
• Geen andere accept header noodzakelijk
• Compact bericht
• eenvoudig aan te geven welke resources geincludeerd moeten worden

Nadelen:

• Maatwerk patroon, geen ondersteuning door bv. libraries. Wel ervaring met dit patroon.
• Consumer moet zelf in de Inclusions de gerelateerde informatie ophalen

HAL Losjes
Voordelen:

• Eigenlijk alleen het toevoegen van een _embedded element met daarin de informatie van de gerelateerde resources
• In die zin vergelijkbaar met inclusions
• eenvoudig aan te geven welke resources geincludeerd moeten worden door query parameters

HAL Strikt
Voordelen:

• Gerelateerde informatie opgenomen op de plek waar het nodig is

• Ondersteuning door libraries. Onduidelijk is nog hoe goed en veelgebruikt deze ondersteuning is.
• Bericht wordt minder compact maar is mogelijk makkelijker te verwerken door consumer omdat informatie op de plek staat waar het nodig is.

Nadelen:

• Kan alleen toegepast worden na een breaking change: Strikt vereist een andere accept header "JSON+HAL"
• Bericht wordt minder compact maar is mogelijk makkelijker te verwerken door consumer omdat informatie op de plek staat waar het nodig is.