Wat is de bedoeling bij _expand bij anderzaakobject in ZRC 1.5?

[johannesbattjes]

Bij een POst op een zaakobject van type anders moet een _expand worden opgegeven:

Vraag 1: waarom heet dit _expand en niet bv ander zaakobject?

Vraag 2: In de response staan vervolgens statustypen en resultaattypen. Waar moet de ZRC deze vandaan halen?

@HenriKorver

[HenriKorver]

Ik zie dat het OAS schema hier niet helemaal goed is. Er zouden geen expand-velden mogen voorkomen op het zaakobjecten endpoint en al helemaal niet op een POST-operatie, je kunt alleen expanden met GET. Trouwens geen van de GET-operaties op dit end-point heeft een expand als query parameter, dus feitelijk kun je hier geen expand uitvoeren.

Zaakobjecten mogen alleen geëxpandeerd worden in de zaken resource. Bijvoorbeeld:

GET /zaken?expand=zaakobjecten of met nesting
GET /zaken?expand=zaakobjecten.zaakobjecttype

[johannesbattjes]

Ja maar hoe moet het dan wel? Bij de POST moet je genoemde gegevens van het zaakobject wel kunnen meegeven

[HenriKorver]

Sorry, ik begrijp je vraag niet. Welke gegevens wil je van het zaakobject meegeven in het POST-bericht?

[johannesbattjes]

Hoi @HenriKorver ik zat de denken aan anderObjecttype maar dat is een denkfout van mij, die hoeft niet mee met de POST.
Dus wat mij betreft is het duidelijk. Kun je nog een indicatie geven van wat er gaat nu gaat gebeuren? Komt er bv een nieuwe versie met nieuw versienummer? Wanneer?

[HenriKorver]

Kun je nog een indicatie geven van wat er gaat nu gaat gebeuren? Komt er bv een nieuwe versie met nieuw versienummer? Wanneer?

Nee, dit ticket heeft helaas geen urgentie. Het is niet fraai dat het endpoint /zaakobjecten expand-velden bevat die er niet thuis horen, maar ze doen ook geen kwaad. Je kunt ze immers niet gebruiken omdat er geen query-parameters zijn om de expand uit te voeren.

Omdat de doorontwikkeling van de referentie-implementatie gepauzeerd is, worden momenteel alleen blokkerende issues en bugs opgepakt. Issues #2242 en #2396 zijn de enige uitzonderingen: ook al zijn dit geen blokkerende issues, zal er toch een nieuwe 1. 5 versie van de Documenten API worden uitgebracht.

[johannesbattjes]

Hoi Henri, mag ik hier uit concluderen dat jullie het prima vinden als er fouten in de standaard staan?

De reden dat dit voor ons belangrijk is:
De standaard en deze OAS zijn uiteraard leidend bij het maken van een DRC. Onze developer kijkt er in bij het maken van de Api's. Hij zei letterlijk (voordat ik dit ticket aanmaakte):
_Ik ben vanmorgen begonnen met ZRC v1.5 zaakobjecten. Wat mij gelijk opvalt is dat in het aanmaken van een zaakobject een
_expand kan worden opgegeven. Waarom heet het hier een expand? Dit is iets anders dan je bij een Get kan doen via query-parameter. Maar goed zal het zo maar gaan implementeren.
Het leidt dus tot fouten
Ik zelf kijk ook in de standaard bij bij het testen.

[HenriKorver]

Hoi Henri, mag ik hier uit concluderen dat jullie het prima vinden als er fouten in de standaard staan?

Natuurlijk niet Johannes, wij vinden het ook heel vervelend als de beschrijvingen in de OAS verwarrend zijn. Gelukkig betreft het hier geen functionele fout maar een probleem met de documentatie in de OAS. Dit heb ik nu opgelost door waarschuwingen op te nemen bij "expand"-velden die niet direct mogen worden gebruikt op endpoints zoals /zaakobjecten en /rollen, maar alleen indirect via het /zaken endpoint.

Ook heb ik de foutieve enumeratiewaarde ZaakObjectExpanded bij zaakobject.objectType verwijderd. Zelfde verhaal voor de enumeratiewaarde RolExpanded bij rol.betrokkeneType.

Zie hier voor de verbeterde OAS: redoc.

[HenriKorver]

Inmiddels heb ik tijd gehad om het probleem op structurele wijze op te lossen. In plaats van waarschuwingen zijn de "_expand" velden nu echt verwijderd op de plekken waar ze niet thuis horen: zie PR #2427 of redoc.

Dit is puur het fixen van de OAS en geen functionele wijziging, m.a.w. er hoeft niets te veranderen aan de referentie-implementatie.

@johannesbattjes: Kun je even checken of de OAS nu naar wens is?

[johannesbattjes]

Ziet er goed uit!
Dank

[johannesbattjes]

Hier staat hij nog:

[HenriKorver]

Hier staat hij nog

Dat klopt want deze fix (PR #2427) is nog niet uitgerold naar de master, dus nog niet officieel gereleased. Intern hebben we nog een discussie of we deze fix wel of niet mogen uitrollen zonder versieverhoging. Hoewel er functioneel niks veranderd is zijn de wijzigingen in het OAS-schema wel substantieel.

Dus de vraag is : rollen we deze wijzigingen uit in de bestaande 1.5.1 versie of verhogen we de versie naar 1.5.2? In dat laatste geval zal de versie van de referentie-implementatie van de Zaken API achterlopen op de OAS, hoewel ze in principe functioneel hetzelfde zijn. Ik zeg hier in principe omdat een patch-verhoging (in dit geval 1.5.1 -> 1.5.2) helaas op een heel subtiel punt het gedrag van de referentie-implementatie verandert. Die moet dan namelijk in de response-headers de nieuwe verhoogde versie teruggeven (1.5.2 in dit geval), hoewel er verder functioneel gezien niets is veranderd.

Wat heeft jouw voorkeur?

[johannesbattjes]

Hoi Henri, mijn voorkeur heeft het uitbrengen van de 1.5.2. Maar geen bezwaar tegen aanpassing aan de 1.5.1 omdat eigenlijk geen enkele applicatie de expand in de POST geimplementeerd kan hebben.

[HenriKorver]

mijn voorkeur heeft het uitbrengen van de 1.5.2.

Dat heeft dan wel als consequentie dat de referentie-implementatie van de Zaken API qua versie achter zal lopen op de OAS omdat we de referentie-implementatie voorlopig niet meer kunnen aanpassen omdat die gepauzeerd is. Dus dan hebben we de situatie dat de OAS van de Zaken API versie 1.5.2 heeft en de bijbehorende referentie-implementatie versie 1.5.1. Heeft het dan nog steeds je voorkeur? Of bedoel je dat je bereid bent te wachten op de 1.5.2 versie totdat de referentie-implementatie weer uit de pauze-stand is gehaald.

[johannesbattjes]

Hoi Henri, jazeker dat bedoelde ik. Op dit moment doe ik zelf weinig met de referentie applicatie dus ik heb zelf geen bezwaar tegen het achterlopen ervan.
In het algemeen lijkt het me dat we verbeteringen in de standaard niet moeten vertragen doordat de referentie-applicatie nog niet bij is.

[HenriKorver]

Dit issue wordt nu opgelost in PR #2483 (voorheen PR #2427).