API omgevingen/endpoints

[marjoleinsteeman]

Omgevingen moeten nog een eigen endpoint krijgen. /v1/erfgoedobject/{id}/omgevingen

Daarnaast graag een kleine aanpassing in de endpoint notaties: /v1/erfgoedobjecten/{id} wordt /v1/erfgoedobject/{id} >> enkelvoud /v1/erfgoedobjecten/{id}/deelobjecten wordt /v1/erfgoedobject/{id}/deelobjecten >> enkelvoud

Kleinigheid in de parameters van endpoint v1/erfgoedobjecten: de parameter situering.betreftAdres graag het prefix situering weglaten. De punt in de veldnaam suggereert een complex datatype; dat is niet wat we willen.

[rcdeboer]

• Endpoint voor omgevingen is toegevoegd.
• Design Rule API-54 schrijft voor dat collecties in meervoud worden aangeduid, en resources die binnen een collectie vallen voorafgegaan worden door de bijbehorende collectienaam (in meervoud). Cf. https://publicatie.centrumvoorstandaarden.nl/api/adr/#api-54 en https://logius-standaarden.github.io/API-Design-Rules/#api-06
• De veldnaam 'situering.betreftAdres' is omgezet naar 'heeftAdres.betreftAdres' (conform informatiemodel). De punt in de aanduiding is in lijn met API-30 (https://docs.geostandaarden.nl/api/API-Strategie-ext/#api-30) inz. 'nested properties'. Zie ook het voorbeeld dat daar wordt gegeven:
  • All objects with the status actief can be filtered using ?status=actief. Filtering objects with code 0000 of the property overheid at the same time, this relates to a nested property. In this case, use the dot notation (like JavaScript): ?status=actief&overheid.code=0000.

[marjoleinsteeman]

Ik begrijp de naamgeving van betreftAdres wel vanuit het informatiemodel. Maar bij coördinaatX en Y houden we ons ook niet precies aan de definitie van puntcoördinaten uit het IM. Waarom zou dat dan hier wel moeten? Ook bij de parameters id en deelobjectid houden we ons niet letterlijk aan de informatiemodel. Kleinigheid: bij de parameter postcode (Local endpoint): postcode zonder spatie schrijven. In de BAG heeft een postcode ook geen spatie tussen de cijfers en de letters.

Bij het opvragen van de deelobjecten zouden we kunnen volstaan met altijd de volledige info ophalen (full). Dus niet in twee stappen. Het gaat om weinig gegevens omdat het per objectid wordt opgehaald. Bovendien zitten er geen adressen aan een deelobject, alleen panden (soms). Heb ik dit eerder niet goed doorgegeven misschien?

Het minimal schema voor Situering en voor Omgevingen wordt niet gebruikt; kunnen deze vervallen? Dit zou dan ook gelden voor het minimal schema van Deelobjecten..

Ten aanzien van de urls heb ik gekeken hoe dit bij de BAG-API is opgezet. Het opnemen van een {id} middenin de url leek nogal bijzonder. Misschien heb ik jullie daar op het verkeerde been gezet. Mijn ontwikkelaar viel erover.. Mijn voorstel is daarom om (in sync met de BAG-API) de urls te vereenvoudigen. Dat zou betekenen dat de deelobjecten worden opgevraagd met /v1/erfgoeddeelobjecten en daarbij een verplichte erfgoedobjectid als parameter. Hetzelfde voor /v1/erfgoedomgevingen. Zie bijvoorbeeld /verblijfsobjecten waarmee je adressen kunt opvragen adhv een pandid.

[rcdeboer]

endpoint /deelobjecten/{id} komt te vervallen. Daarmee komt ook het minimal-schema te vervallen voor Deelobjecten (net als Situering en Omgeving)

De deelobjecten-URL vereenvoudigen conform voorstel hierboven. (/v1/erfgoedobjecten/{id}/deelobjecten wordt /v1/deelobjecten met request parameter objectid)

[marjoleinsteeman]

Kleinigheid: graag bij de parameter straal vermelden dat deze alleen wordt gebruikt in combinatie met x en y coördinaat. Als de straal wordt weggelaten is een default waarde van toepassing van 100 meter.

Moeten wij die 100 meter (default) opnemen in de standaard, denk je? Of is het slimmer om dat over te laten aan de toepassing? Moeten we dan vermelden dat een default waarde van toepassing kan zijn?

[rcdeboer]

Het lijkt me zinnig om van een standaardwaarde uit te gaan; toegevoegd.