Als gebruiker van de Zaken API wil ik de expand-parameter kunnen meegeven aan de /zaken endpoint

[alextreme]

...zodat ook de gerelateerde informatie van de zaak (status, zaakobjecten en zaakinformatieobjecten) teruggegeven wordt in het antwoord

Momenteel is het zo dat er na een GET /zaken additionele opvragingen op de status, zaakobjecten en zaakinformatieobjecten resources binnen de Zaken API nodig zijn om ook de gerelateerde informatie van de zaak op te vragen. Dit zorgt voor additionele complexiteit aan de kant van clients (ik moet als gebruiker meer API calls uitvoeren) en lagere performance (de gegevens in 1x opvragen gaat sneller dan met vele losse opvragingen).

Mijn voorstel is om op de GET /zaken endpoint de ?expand parameter te introduceren. Eerder is deze parameter aan bod gekomen in #932 , #389 en #278 echter deze issues zijn redelijk algemeen verwoord. Deze issue is een concreet voorstel om dit binnen de Zaken API te introduceren.

Voor de voorgestelde implementatie voegen we ?expand toe om op verzoek van de client de gerelateerde informatie (rollen, resultaten, status, zaakverzoeken, zaakobjecten en zaakinformatieobjecten) terug te krijgen.

Werking van deze parameter:

GET /zaken?expand=rollen,status

{
    ...
    "results": 
[ {
    "url": "http://example.com",
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "status": {
        "....",
        "zaak": "http://example.com",
        "statustype": "http://example.com",
        "datumStatusGezet": "2019-08-24T14:15:22Z",
        "statustoelichting": "string"
    },
    "rollen": [{
        "....",
        "zaak": "http://example.com",
        "betrokkene": "http://example.com",
        ...
     }],
     ....
}]}

Hier zien wij dat de bestaande "status" veld vervangen wordt door het geneste resource van /statussen

Daar waar er geen bestaande veld is worden de geneste resources als lijsten van URLs toegevoegd aan de reguliere /zaken endpoint. Dus aan de reguliere /zaken resultaten worden: "rollen": [URI-1, URI-2, URI-3] toegevoegd, en dit veld wordt zoals hierboven aangepast van URI-X naar de geneste resources. Dit betekent wel dat GET /zaken ook zonder de expand-parameter wordt aangepast, echter anders ben je velden aan het 'expanden' die er nu niet zijn wat ons niet logisch lijkt.

Complicerende factor is dat je afhankelijk van de resource altijd 1 object terug krijgt (zoals bij statussen) of meerdere (zoals bij rollen). Mijn voorstel is dat dit per resource wordt bepaald en bij het tweede dat er een lijst van objecten wordt teruggegeven zoals in bovenstaand voorbeeld.

Aandacht moet worden besteed aan eventuele afwijkende permissies van de API gebruiker bij deze resources. Hoewel je op hoofdlijnen op zaak-niveau lees/schrijf permissies hebt, er kunnen nested resources zijn waar je als gebruiker geen toegang toe hebt. In dat geval zou de API 403 Forbidden mogen terugkeren.

Daarnaast zouden we verwachten dat de expand-parameter naast op de zaken-lijst ook op de zaken-details endpoint mogelijk is om de consistentie tussen beiden te bewaren.

[michielverhoef]

Gezien de discussie over het te gebruiken formaat (HAL, Inclusions, ??) kan het zomaar zijn dat deze oplsosingsrichting niet gevolgd wordt.

#1960

[alextreme]

@michielverhoef dat is wat ons betreft prima en ik ben blij dat er stappen hiervoor worden gezet.

Zelf vind ik het genest toevoegen van andere resources makkelijker in gebruik maar het toevoegen van de inclusions zoals Sergei dat voorstelt lost het onderliggende probleem ook op.

Het is wel aan jou of je dan bij het introduceren van inclusions de gemergde expand-parameter wilt uitfaseren ( VNG-Realisatie/zaken-api#207 ).

[michielverhoef]

Het besluit om inclusions door te voeren is nog niet genomen. Er zijn veel goede argumenten om bijvoorbeeld HAL toe te passen.

Het is wel beter om zoveel mogelijk dezelfde methode overal toe te passen en aangezien de expand parameter nog niet in een gereleasede versie van de Zaken API is gepubliceerd moet hier inderdaad even goed naar gekeken worden.

[michielverhoef]

@SonnyBA Omdat we een ander patroon toe gaan passen en dit consequent willen doen moet de eeder al gemergede PR (VNG-Realisatie/zaken-api#207) weer terug gedraaid worden.

[michielverhoef]

Opgenomen in Zaken API 1.5.0

[alextreme]

Veel dank @michielverhoef ! Erg fijn dat jullie dit in 1.5 hebben meegenomen