Meerdere of slechts 1 verblijfplaats mogelijk? about haal-centraal-brp-bevragen HOT 9 CLOSED

Deze keuze is gemaakt vanuit de gedachte dat we bij de naamgeving van het element ons conformeren aan de API-strategie dat resourcenamen in meervoud worden gedefinieerd (API-08).

We kunnen natuurlijk ook het element in enkelvoud weergeven als deze maximaal 1 keer kan voorkomen. Dat betekent wel dat die regel ook toegepast moet worden bij het maken van het berichtmodel. Dan moet je dus met de naamgeving van het element rekening houden met de kardinaliteit.
Ik maak er voor nu "Verblijfsplaats" van en stel bovenstaande voor als "best practice" te definieren.
Frank, Robert, Henri, Michiel wat denken jullie van die best practice ?

from haal-centraal-brp-bevragen.

Eens met @michielverhoef. Trouwens in het RSGB bestaat het begripverblijfsplaats niet. Daar heet het verblijfadres. Of volgen jullie (@JohanBoer ) nu rechtstreeks het LO GBA (3.10)?

from haal-centraal-brp-bevragen.

Als ik kijk naar de API voor de ZRC is daar ook iets dergelijks gedaan met het zaaktype. Ook daar is zaaktype als enkelvoudig attribuut opgenomen.

Ik vind het voorstel wel overzichtelijk, dan kan er ook geen onduidelijkheid over bestaan. Zelfs een ontwikkelaar die niet naar het informatiemodel gekeken heeft zou dan moeten snappen dat een natuurlijk persoon maar 1 verblijfplaats kan hebben.

from haal-centraal-brp-bevragen.

@HenriKorver Klopt. We hebben het verblijfsadres, nummeraanduiding, openbare ruimte en woonplaats platgeslagen tot een resource en de wens van Den Haag was om dan in de naamgeving het LO GBA te volgen.

from haal-centraal-brp-bevragen.

Is verblijfsplaats wel een resource in jullie oas-specificatie? Ik zie namelijk geen endpoint /verblijfsplaatsen, dus je kunt er niet naar linken. Het lijkt meer op een geneste (JSON) structuur, vroeger noemden we dat een groep.

from haal-centraal-brp-bevragen.

De OAS is nog niet klaar, en daarom zijn sommige resources nog niet gedefinieerd. Maar een endpoint /verblijfplaats(en) komt er wel (anders is het immers geen resource).

Wanneer we enkelvoud/meervoud laten afhangen van de kardinaliteit moeten we wel oppassen dat we deze keuze niet per API maken, maar op overkoepelend niveau. Anders heet hetzelfde ding op de ene plek verblijfplaats en op de andere plek verblijfplaatsen.
Verder ben ik het er wel mee eens dat de API vooral duidelijk moet zijn. En een relatienaam in meervoud als die maar één keer kan voorkomen is verwarrend.

from haal-centraal-brp-bevragen.

Als de resource /verblijfplaatsen er komt, dan is die als endpoint natuurlijk in meervoud. Immers los van de persoon zijn er natuurlijk meerdere verblijfplaatsen. Maar vanuit persoon is er maar één (ingeschreven) verblijfplaats. Dus de naam van de link in de response van bijvoorbeeld /ingeschrevennatuurlijkpersonen/123456789 die verwijst naar de verblijfplaats zou ik in enkelvoud houden.

from haal-centraal-brp-bevragen.

De verblijfplaats van een persoon zou je ook kunnen modelleren als een sub-resource:

/ingeschrevennatuurlijkpersonen/{burgerservicenummer}/verblijfplaats(en)

Ook hier is het weer de vraag welke conventie we moeten volgen: enkel- of meervoud. Zo snel heb ik op het internet hierover nog geen best practice gevonden. Zover ik weet zijn binnen het ZDS-project alle sub-resources meervoudig (sub-collections) en hebben we nog geen ervaring met deze situatie.

from haal-centraal-brp-bevragen.

Resource URLs en attribuut name moeten verschillend worden behandeld. Het attribuut "verblijfplaats" is logisch. De resource URL (altijd meervoud) "verblijfplaatsen" is ook logisch want je krijgt altijd een lijst met verblijfplaatsen (op root niveau).

Hoewel ik voorheen voorstander was van subresources (veel gedaan voor ZTC) ben ik steeds minder fan geworden door praktische problemen. Ook hier denk ik dat het geen subresource moet zijn.

De vraag: Wie woont er op dit adres, zou je typisch kunnen doen door /api/v1/ingeschreven natuurlijk persoon?verblijfplaats=/api/v1/verblijfplaatsen/<uuid> (pseudo call)

Het zou vreemd zijn als je de query parameter van verblijfplaats al onder een persoon zou hangen. Je wil immers weten wie er wonen en dit zou betekenen dat je al 1 iemand weet.

Als er overigens goede redenen zijn om het wel te doen, moeten we het gewoon doen maar meestal is voor mij de vraag of ik de resource ooit zelfstandig zou gebruiken en dan betekenis heeft. Is het antwoord ja, dan geen subresource.

from haal-centraal-brp-bevragen.