Als ontwikkelaar wil ik slechts 1 endpoint voor het raadplegen van een resource about haal-centraal-brp-bevragen HOT 12 CLOSED

Beste Joeri, ik denk dat je gelijk hebt, ons experiment is inderdaad enigszins doorgeslagen :-). Hier is voor ieder zoekpad als aparte resource gedefinieerd, met als resultaat een wildgroei aan resources. En dat terwijl de query parameter speciaal voor dit doel in het leven is geroepen.

Nu wordt deze API de komende jaren in theorie nog op 380 plekken aangeboden (geen Landelijke Registratie), en we willen bereiken dat consumers van binnengemeentelijke afnemers in meer, zo niet alle gemeenten (met minimale aanpassingen) kunnen worden hergebruikt. Dan is het belangrijk om duidelijk te maken welke zoekpaden (minimaal) moeten worden ondersteund. Op deze manier kom je al een heel eind:

/ingeschrevennatuurlijkpersonen?geslachtsnaam={geslachtsnaam}
/ingeschrevennatuurlijkpersonen?geslachtsnaam={geslachtsnaam}&geboortedatum={geboortedatum}
..... etc.

Je hebt gelijk dat dit moet worden aangevuld met documentatie in natuurlijke taal.
Omdat dit bovendien niet allemaal door het API contract kan worden gevalideerd, zou VNG Realisatie misschien een testconsumer kunnen maken die valideert of de API de gespecificeerde paden (op de juiste manier) implementeert (toets op interoperabiliteit) en of de minder wenselijke combinaties van queryparameters adequaat worden geweerd (toets kwaliteit oplossing).

Dit gezegd hebbende: het is mijn inziens niet zo dat een resource hetzelfde is als een entiteit en deze slechts via 1 endpoint moet kunnen worden gevonden.
De discussie binnen de werkgroep is ontstaan naar aanleiding van het zoeken van een ingeschreven natuurlijk persoon op postcode en huisnummer. De postcode en huisnummer zijn in principe adresgegevens en horen bij een ander domein (BAG), waarbij de relatie wordt beheerd in de BRP. Bij een fijnmazige opzet van resources zoek je dan met de postcode/hn een BAGID en via het BAGID de ingeschreven natuurlijke personen. Om te voorkomen dat deze logica bij de consumer wordt gelegd (die dan domeinkennis moet hebben), zou je kunnen aanbieden:

/ingeschrevennatuurlijkpersonen?postcode={postcode}&huisnummer={huisnummer}
en bijv. zelf in je implementatie van de provider de relatie leggen via de BAG.

Je kunt ook zeggen: we maken van deze relatie een resource. Ook deze geeft met GET ingeschreven natuurlijke personen terug:

/bewoning?postcode={postcode}&huisnummer={huisnummer}
/bewoning?nummeraanduiding={nummeraanduiding}

De introductie van dit nieuwe endpoint heeft de volgende voordelen:

• in dit geval kan beter worden voldaan aan de businessvraag van afnemers. De informatiebehoefte van afnemers heeft vaak betrekking op relaties, en heel vaak als het historie betreft. Zo ook in de requirements van Bevragingen Ingeschreven Personen. Heel belangrijk is de businessvraag: wie woonde er op (binnen welke periode) op dit adres? Moet je deze "bewoning" dan meegeven als relaties van een nummeraanduiding resource? Dat gaat niet. Denken in termen van resource=een entiteit, laat een hele wereld aan mogelijkheden liggen die voor een gebruiker belangrijk, relevant en betekenisvol zijn.
• Semantisch duidelijker en intuitiever zoeken voor een gebruiker (bewoning associeer ik met adres/ verblijfsobject, persoon met geboortedatum en andere persoonskenmerken).
• het onderliggende model wordt naar je gebruikers toe expliciet en inzichelijker (ik zoek kennelijk op een relatie, hoe ziet dat er uit, misschien wel met een ander domein, misschien ook wel met een andere eigenaar/beheerder...).

Tenslotte: dit is geen pleidooi om van alle relaties tussen objecten een resource te gaan definieren! In tegendeel. Ben wel groot voorstander om dit te doen als dit invulling geeft aan een concrete businessvraag van afnemers.

from haal-centraal-brp-bevragen.

Beste Joeri, ik denk dat je gelijk hebt, dit experiment is inderdaad enigszins doorgeslagen

Ha Cathy. Bedankt voor je antwoord. Experimenteren hoort er bij!

Je gaat wel op een aantal andere punten in die wellicht een eigen issue mogen hebben maar dat laat ik aan jullie. Ik ga er kort even op in.

Dit gezegd hebbende: het is mijn inziens niet zo dat een resource hetzelfde is als een entiteit en deze slechts via 1 endpoint moet kunnen worden gevonden [...] Ook deze GET geeft ingeschreven natuurlijke personen terug: /bewoners? postcode={postcode}& huisnummer={huisnummer}

Helemaal mee eens, in dit voorbeeld.

De discussie binnen de werkgroep is ontstaan naar aanleiding van het zoeken van een ingeschreven natuurlijk persoon op postcode en huisnummer. De postcode en huisnummer zijn in principe adresgegevens en horen bij een ander domein (BAG), waarbij de relatie wordt beheerd in de BRP. Bij een fijnmazige opzet van resources zoek je dan met de postcode/hn een BAGID en via het BAGID de ingeschreven natuurlijke personen. Om te voorkomen dat deze logica bij de consumer wordt gelegd (die dan domeinkennis moet hebben), zou je kunnen aanbieden:
/ingeschrevennatuurlijkpersonen? postcode={postcode}& huisnummer={huisnummer}
en bijv. zelf in je implementatie van de provider de relatie leggen via de BAG.

Ik begrijp de functionele wens maar volgens mij is dat in de onderste service laag niet handig.

Precies wat je aangeeft, moet de consumer in deze situatie 2 calls maken, wat mij helemaal niet erg lijkt. Er moeten altijd 2 calls gemaakt worden, alleen in je voorbeeld wordt de 2e call gedaan door de API naar aanleiding van de 1e call. Dit impliceert een aantal zaken, maar grofweg: API 1 moet kennis van, en toegang hebben tot API 2.

Als deze functionele wens een vaak gebruikt scenario is, dan kan het wel, maar ik zou dat in een hoger gelegen API oplossen (composite API layer) die de API die jullie hier aan het bouwen zijn aanspreekt. In die laag kan je dan ook meer kennis regelen van verschillende API's, credential forwardering (oid) en meer applicatie gerichte API's maken.

Echter, het ontbreken van een composite API maakt de functionele vraag niet onmogelijk (2 calls door consumer).

• Semantisch duidelijker en intuitiever zoeken voor een gebruiker (bewoning associeer ik met adres/ verblijfsobject, persoon met geboortedatum en andere persoonskenmerken).
• het onderliggende model wordt naar je gebruikers toe inzichelijker (ik zoek op een relatie, misschien wel met een ander domein, misschien ook wel met en andere eigenaar/beheerder...).

Het klinkt alsof je wilt dat deze API's door (eind)gebruikers gebruikt moeten gaan worden? Dat lijkt mij nooit het geval. Als je doelt op ontwikkelaars, die komen er wel uit. En leveranciers moeten een mooie gebruikersvriendelijke interface er op bouwen in de applicatie laag die niets weg heeft van hoe een API er uit ziet.

Tenslotte: dit is geen pleidooi om van alle relaties tussen objecten een resource te gaan definieren! In tegendeel. Ik stel wel voor om dit te doen als dit invulling geeft aan een concrete businessvraag van afnemers.

Ah, nog een heet hangijzer :) Ik denk dat je er toch niet om heen kunt dat elke relatie een resource wordt. Zodra je informatie bij een relatie (bijvoorbeeld: wanneer is de relatie gelegd, door wie, wat is de context) wilt opslaan is deze noodzakelijk. Ik denk dat hier genoeg business vragen voor zijn. ALs dat niet zo is, dan moeten we het inderdaad niet doen!

from haal-centraal-brp-bevragen.

Ha Joeri, dank voor je reactie.

Precies wat je aangeeft, moet de consumer in deze situatie 2 calls maken, wat mij helemaal niet erg lijkt.

Dit is niet wat ik aangeef....

Het klinkt alsof je wilt dat deze API's door (eind)gebruikers gebruikt moeten gaan worden? Dat lijkt mij nooit het geval. Als je doelt op ontwikkelaars, die komen er wel uit. En leveranciers moeten een mooie gebruikersvriendelijke interface er op bouwen in de applicatie laag die niets weg heeft van hoe een API er uit ziet.

Nee hoor, dat bedoel ik niet. Ook voor mij zijn ontwikkelaars gebruikers van API's.

Ik begrijp de functionele wens maar volgens mij is dat in de onderste service laag niet handig.

Als deze functionele wens een vaak gebruikt scenario is, dan kan het wel, maar ik zou dat in een hoger gelegen API oplossen (composite API layer) die de API die jullie hier aan het bouwen zijn aanspreekt. In die laag kan je dan ook meer kennis regelen van verschillende API's, credential forwardering (oid) en meer applicatie gerichte API's maken.

Jouw assumpties over wat wij aan het definieren zijn, herken ik niet helemaal. Kun je dit verduidelijken/toelichten?

from haal-centraal-brp-bevragen.

Kans dat we langs elkaar heen commenten, dus wellicht face-to-face even bespreken?

from haal-centraal-brp-bevragen.

Prima, spreek je op de fieldlab!

from haal-centraal-brp-bevragen.

Naar mijn idee is dit issue nu opgelost, door niet meer specifieke endpoints per combinatie van query parameters te definiëren.

from haal-centraal-brp-bevragen.

Zie beslissing

from haal-centraal-brp-bevragen.

Top. Had zelfs generieker gemogen maar prima voor nu.

Merk wel in ZDS traject dat dit ook in de OAS moet staan als description can de parameters en niet alleen in een docje.

from haal-centraal-brp-bevragen.

@johan, kan je de toegestane combinaties van parameters ook in de description van operatie ingeschrevennatuurlijkpersonen toevoegen?

Er kan gezocht worden met verschillende zoekpaden van zoekparameters:

• ?geslachtsnaam={}&geboortedatum={}&voornamen={}&voorvoegselGeslachtsnaam={}&geslachtsaanduiding={}&geboorteplaats={}&gemeenteVanInschrijving={}&inclusiefnietingezetenen={}&page={}&expand={}&sort={}
• postcode={}&huisnummer={}&huisletter={}&huisnummertoevoeging={}&page={}&expand={}&sort={}
• woonplaatsnaam={}&naamopenbareruimte={}&huisnummer={}&huisletter={}&huisnummertoevoeging={}&page={}&expand={}&sort={}
• identificatiecodeNummeraanduiding={}&page={}&expand={}&sort={}

@joeri, is dit een duidelijke manier voor een developer om dit aan te geven?

from haal-centraal-brp-bevragen.

@fsamwel Idee lijkt me prima. Paar suggesties: Het hoeft niet perse als querystring, mag ook met bullets of komma gescheiden; ik zou ook aangeven welke optioneel zijn (zoals huisletter); en algemene query params weglaten (page, expand)

Er kan gezocht worden met verschillende zoekpaden van zoekparameters:

Adres

• postcode
• huisnummer
• huisletter (optioneel)
• huisnummertoevoeging (optioneel)

Persoon
...

from haal-centraal-brp-bevragen.

@JohanBoer: kan je dit ook op endpoint/method niveau in de description zetten? Voorstel van Joeri (bullitted lijsten) lijkt mij ook duidelijk.

from haal-centraal-brp-bevragen.

Voorstel is duidelijk, maar als ik in EA een description opneem dan worden de line-feeds er door Imvertor uitgesloopt. Ik kan dus wel een aantal MARKDOWN edit-faciliteiten gebruiken, maar de bullited list vereist linefeeds. De gewenste beschrijvingen neem ik op en ik maak voor nu met de hand de bullited listen aan. Ik zal een issue indienen om dit ook uit Imvertor te kunnen laten rollen. Komt er uiteindelijk zo uit te zien

from haal-centraal-brp-bevragen.