Als gebruiker van de Documenten API wil ik de documenten van een zaak kunnen opvragen

[alextreme]

...zodat ik niet langer voor elk document een individuele aanroep op /enkelvoudiginformatieobject/{uuid}/ moet uitvoeren.

Dit is een verfijning van #1881 van @joeribekker

Concreet is het voorstel om bij de GET /enkelvoudiginformatieobjecten een object-parameter mee te geven. Onderhuids zou de Documenten API op basis van de aanwezige objectinformatieobjecten alleen die documentdetails teruggeven die gerelateerd zijn aan de URL die wordt meegegeven:

GET /enkelvoudiginformatieobjecten?object=https://zaken-api/zaken/{uuid}/

Dit zou de huidige lijst-output van documentendetails terugkeren, maar gefilterd op die documenten die via de objectinformatieobjecten gelinkt zijn aan de URL van de object-parameter. Dit kan een Zaak URL zijn of een andere API URL (zodat in de toekomst dit ook voor verzoeken ingezet kan worden)

Complicerende factor is dat het niet duidelijk is aan de kant van de Zaken API hoe deze documenten opgevraagd kunnen worden. Dit kan namelijk ook over meerdere Documenten APIs heen plaatsvinden.

Ons voorstel omvat dan tegelijkertijd de volgende uitbreiding op de GET /zaken en GET /zaken/{uuid} endpoints van de Zaken API, zodat vanuit de Zaken API alle gerelateerde documenten opgevraagd kunnen worden zonder dat URLs van de zaakinformatieobjecten gefiltered moeten worden:

GET /zaken

{
    ...
    "results": 
[ {
    "url": "http://example.com",
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "enkelvoudiginformatieobjecten": [
        "https://document-API-1/?object=https://zaken-api/zaken/095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "https://document-API-2/?object=https://zaken-api/zaken/095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
    ],
    ...
}]
}

[michielverhoef]

In het tweede deel van het voorstel zie ik een expand van rollen en statussen maar dit moet denk ik een expand van informatieobjecten zijn. Maar dat is een detail :-).

Wat voegt het opnemen van de urls naar informatieobjecten in een zaak toe ten opzichte van het opvragen van de zaakinformatieobjecten? Je krijgt immers dezelfde informatie (de urls naar de documenten) en nog steeds kun je niet in één keer aan een DRC de documenten in bulk opvragen.

Het lastige is in dit geval dat er meerdere DRCs kunnen bestaan, zoals je zelf ook aangeeft. Bovendien wil je het voor de consumer zo simpel mogelijk houden.

Zou het niet veel makkelijker (los van technische issues) zijn om iets te doen als:
/zrc/zaakinformatieobjecten?expand=informatieobject en in dit geval de ZRC onder water een bulkaanroep te laten doen naar de DRC's met een lijst UUIDs? Voor dit laatste is dan de #1728 nodig.

[alextreme]

Dank voor je antwoord!

Goed gezien en bij deze heb ik het voorbeeld aangepast, echter mijn voorstel zou zijn om deze DRC+ZRC wijziging los te zien van de 'expand' parameter en dus vanuit de ZRC de URLs naar de bijbehorende Documenten APIs altijd mee te geven. Al zou je het ook aan een optionele argument kunnen koppelen mocht je dit niet standaard willen terugkoppelen, het is een gedachte om te zorgen dat je eenvoudig zicht hebt via welke DRCs de documenten van een zaak opgevraagd kunnen worden maar het is geen must en ik vind het ook prima om dit voor nu achterwege te laten (we zijn het meest gebaat bij de DRC ?object queryparameter)

Het voordeel met de ZRC-aanpassing is dat je dan als consumer weet per zaak welke DRCs je dient te raadplegen om de bijbehorende informatieobjecten op te vragen. In de regel zal dat er maar 1 zijn, maar mochten het toevallig meerdere zijn dan kun je alle URLs volgen om bij de bijbehorende informatieobjecten te komen. Enige waar je dan als consumer rekening mee moet houden zijn verschillende credentials.

De URLs die hier in zijn opgenomen geven je in 1x alle bijbehorende documenten per DRC, in plaats van dat je dit per document moet opvragen (sommige zaken hebben 300 documenten met achterliggende DMS-integraties, ze stuk voor stuk ophalen geeft een behoorlijke vertraging). Het alternatief is dat je de URLs van de individuele zaakinformatieobjecten moet gaan parsen om de relevante DRCs te bepalen, wat in mijn ogen niet de schoonheidsprijs verdient.

Je oplossing om via de zaakinformatieobjecten de UUIDs in bulk op te vragen kan ook (zie ook de discussie tussen Joeri en Sergei hierover in #1881 ) en beiden zouden het probleem qua performance kunnen oplossen. Het een zou de ander ook niet hoeven uit te sluiten.

Echter na het met Sergei en Joeri te hebben besproken vinden we de 'developer experience' bij de voorgestelde UUID oplossing via een bulk/zoek endpoint eigenlijk ingewikkelder dan nodig. Je wilt in de ideale situatie als API gebruiker de lijst van documenten van een zaak in 1x kunnen opvragen zonder tussenstappen.

[michielverhoef]

Het voordeel met de ZRC-aanpassing is dat je dan als consumer weet per zaak welke DRCs je dient te raadplegen om de bijbehorende informatieobjecten op te vragen. In de regel zal dat er maar 1 zijn, maar mochten het toevallig meerdere zijn dan kun je alle URLs volgen om bij de bijbehorende informatieobjecten te komen. Enige waar je dan als consumer rekening mee moet houden zijn verschillende credentials.
...
Je wilt in de ideale situatie als API gebruiker de lijst van documenten van een zaak in 1x kunnen opvragen zonder tussenstappen.

Ik blijf even advocaat van de duivel spelen :-)

In 1 aanroep een lijst van de documenten die bij een zaak horen kan al door aan de ZRC de Zaakinformatieobjecten op te vragen. Dan heb je nog niet de metagegevens van die documenten maar die zou je ook niet hebben wanneer je de urls opneemt in de zaak. Wel heb je dan de DRCs die geraadpleegd moeten worden, die informatie staat immers in de urls.

Omdat het twee verschillende registers zijn kun je niet met 1 aanroep alle informatie (lijst met documenten en de metagegevens van die documenten) ophalen. Daar heb je minimaal 2 aanroepen voor nodig, meer wanneer er meer dan 1 DRC is.

Om als consumer zo min mogelijk werk te hebben, is het dan niet veel eenvoudiger om in plaats van de UUIDs de gehele url in een bulk aanroep naar de DRCs te sturen? Hoewel, je zult dan nog de url uit elkaar moeten knippen om te weten welke DRCs je moet raadplegen. Tenzij die informatie ook opgenomen wordt in het zaakinformatieobject.

Ons voorstel omvat dan tegelijkertijd de volgende uitbreiding op de GET /zaken en GET /zaken/{uuid} endpoints van de Zaken API, zodat vanuit de Zaken API alle gerelateerde documenten opgevraagd kunnen worden zonder dat URLs van de zaakinformatieobjecten gefiltered moeten worden:

Dit voorstel vind ik niet goed. Los van het feit dat er ook nog zoiets als samengesteldeinformatieobjecten bestaat (SDC, komt in een volgende versie van de Documenten API) is de informatie die daar in staat geen enkelvoudiginfoprmatieobject maar een verwijzing naar één of meer DRCs waar documenten staan die bij deze zaak horen.

Afgelopen architectuuroverleg is deze casus besproken, ook om eens de mening van anderen hier over te horen. Eigenlijk kwamen we tot de conclusie dat dit soort functionaliteit heel wenselijk is maar niet echt REST. De vraag is dus of dit soort complexere bevragingen niet beter anders opgelost kunnen worden. Bijvoorbeeld door niet alleen de losse resources te benaderen maar het geheel (zaak + gerelateerde resources) terug te geven. Dan kun je dit soort dingen echt in 1 call oplossen.
Bij wijze van spreken een soort HaalCentraal voor zaken.

[alextreme]

Het gaat hier primair om de metagegevens van documenten (je wilt een lijst van documenten-namen / eigenschappen tonen bij een zaak). Vind je het dan wel acceptabel om bijvoorbeeld ons verzoek te beperken tot de DRC aanpassing en het ZRC te laten voor wat het is?

Het primaire verzoek is immers om de metagegevens via de DRC in 1x op te vragen voor een objectinformatieobject (dus de andere kant op):

GET /enkelvoudiginformatieobjecten?object=https://zaken-api/zaken/{uuid}/

Dit voorkomt URL-parsing, en als we dan als consumer alleen rekening hoeven te houden dat er in bepaalde situaties meerdere DRCs kunnen zijn dan is dat prima via de zaakinformatieobjecten af te leiden. Het gaat met name om de eenvoud bij het tonen van documenten en de performanceverbeteringen die we met deze DRC aanpassing voor elkaar kunnen krijgen (en dit onderdeel is volgens mij prima compatible met REST)