Als ontwikkelaar wil ik bij het opvragen van entiteit ook eigenschappen van gerelateerde entiteiten opnemen

[JohanBoer]

...zodat het aantal calls wordt beperkt in de situatie dat er veel voorkomende combinaties van elementen uit verschillende gerelateerde entiteiten zijn.

Definition of ready

• Iedereen in het team begrijpt de user story
• Is klein genoeg (maximaal 1/5 van sprint)
• Product Owner akkoord
• Voorzien van acceptatiecriteria (duidelijk en testbaar)
• Voorzien van Definition of Done (duidelijk en testbaar)
• Voorzien van taken
• Vastgelegd Github en in geplaatst in kolom ready

Definition of done

• er is een voorbeeld van hoe dit in een OAS 3.0 specificatie wordt opgenomen
• de gemaakte ontwerpkeuzes zijn gedocumenteerd
  [ ] er zijn geen (nieuwe) conflicten met ontwerp keuzes in BIP
• de specificatie is gepubliceerd leesbaar
• de DSO URI- en API-strategie worden gevolgd

Acceptatiecriteria
Uit de algemene uitgangspunten:

• Voldoet aan RGBZ 2.0
• Voldoet aan GEMMA 2.0

Taken

• Visie op geneste entiteiten formuleren [verantwoordelijke]
• Discussie voeren (waar nodig)
• Voorbeeldspecificatie OAS3 opstellen [verantwoordelijke]
• Genereren/opstellen van OAS 3.0 [verantwoordelijke]
• Vastleggen \design Decission [verantwoordelijke]

[JohanBoer]

In de API's die binnen het project "Bevragingen ingeschreven persoon" worden elementen van gerelateerde entiteiten "embedded" opgenomen volgens JSON Hal. Als we geen JSON Hal gaan toepassen gaan we dan gebruik maken van geneste entiteiten ?
In de huidige API van Gemma-zaken zie ik daar geen voorbeeld van aangezien van alle gerelateerde entiteiten alleen de links worden opgenomen in de response.
Ik ben benieuwd hoe binnen het project Gemma-Zaken tegen het nesten van entiteiten wordt aangekeken.

[sergei-maertens]

Dit is binnen gemma-zaken nog niet concreet geimplementeerd, maar we volgen hier wel de DSO API-strategie (API-10)

Resources ondersteunen “lazy” en “eager” laden van relaties
Resources die een n-op-n relatie kennen ondersteunen zowel het teruggeven van identificaties van
gerelateerde resources (lazy loading) als het teruggeven van de resources zelf (eager loading).

Voorbeeld:

GET /aanvragen/12?expand=aanvrager.naam,bevoegd_gezag

Doordat we JSON Hal hier niet zo fijn vinden, worden deze resources dan inline genest.

Concreet kan dat dus worden:

GET /api/v1/zaken/1234?expand=status

{
    "identificatie": "1234",
    "bronorganisatie": "56789",
    "status": {
        "url": "...",
        "statusType": "https://ztc/api/v1/statustypen/123456789",
        ...
    }
}

Zonder de expand parameter, krijg je hier een URL terug in plaats van een embedded object.

Merk op dat deze relaties niet altijd ge-expand kunnen worden. Binnen een zaak het zaaktype expanden bijvoorbeeld kan niet omdat dit een referentie is naar een component uit een andere API (ZRC vs. ZTC).

[sergei-maertens]

Nog even wat research gedaan, maar deze verschillende shapes van responses uitdrukken op basis van GET parameters is zo te zien niet mogelijk in OAS 3.0, zie OAI/OpenAPI-Specification#56

[sergei-maertens]

Mogelijks is oneOf een uitweg, maar dan moet er ook een discriminator waarde + key toegevoegd worden, wat het weer complexer maakt... want de discriminator in dit geval is de volledige expand parameter waarde (waarbij volgorde niet uitmaakt).

Denk dat dit een gevalletje worden basis opnemen in API spec + expand gedrag opnemen in standaard.md en correct implementeren in referentie-implementatie ter verduidelijking.

[joeribekker]

Besloten tijdens overleg d.d. 17 september 2018

We implementeren expand zonder HAL. In de documentatie moet dit naar voren komen EN er moet vermeld worden dat expand de OpenAPI elementen worden veranderd (lees: de spec klopt niet meer want er staat opeens een object waar eerst een linkje stond).

[ehotting]

Design choice met behoorlijke impact, s.v.p. uitwerken en afronden in afstemming met RSGB team

[TCIMEddy]

@joeribekker @Hugo-ter-Doest Weten jullie de status?

[TCIMEddy]

@joeribekker @Hugo-ter-Doest Goed punt maar ik weet niet of we dit moeten en kunnen realiseren.

[Hugo-ter-Doest]

Ik stel voor: label convenience maken, en later samen met andere gelijksoortige uitbreidingen voor gemak bepalen wat ermee te doen.

[michielverhoef]

opgenomen in Zaken API 1.5.0