[verbetervoorstel] aanscherping ADR#54 - versoepeling eis meervoudsvorm collectienamen voor bestaande datasets en dataset namen

[RoelvandenBerg]

Paragraaf nummer:

API Design rule #54

Korte omschrijving:

Voor bestaande modellen en datasets breekt API-designrule 54, die vereist dat collectienamen meervoudig worden opgenomen in een api, het gebruik van de betreffende collecties tussen verschillende bronnen. Voorstel is dit alleen voor nieuwe collecties te vereisen (MUST) en voor bestaande, breed gebruikte collectienamen te adviseren (SHOULD). Een regel om (zoveel mogelijk) de meervoudsvorm te kiezen heeft de voorkeur boven geen regel.

Vigerend gebruik van collectienamen van bestaande datasets met bestaande modellen zou hier in de afweging meegenomen moeten worden. Aangezien het hernoemen van collecties tussen verschillende services en bronnen het makkelijk combineren van data in de weg zit. Als API design rule 54 in een dergelijk voorbeeld toegepast wordt maakt dit het gebruik van die API lastiger. Er zal dan in het gebruik namelijk ook altijd een mens nodig zijn om de mapping van enkelvoud naar meervoud te maken.

Waarbij ik specifiek een uitzondering betoog voor OGC APIs waar door gebruik van meervoudsvormen in de endpoints waar de collecties bevraagd kunnen worden (bijvoorbeeld: {collection_name}/items) het semantische probleem in die APIs wordt opgelost.

Lange omschrijving:

De api design rule schrijft voor dat collectienamen in meervoud moet zijn. Hoewel dit voor nieuwe collecties nastrevenswaardig is, zal het breed vereisen, voor bestaande modellen, betekenen dat deze naamgeving ingrijpt op de (meta)data. Daarbij geldt dat het verschil tussen enkelvoud en meervoud alleen taalkundig is af te leiden, en in vele gevallen zelfs taalkundig niet bestaat. Deze regel is daarmee überhaupt niet voor alle mogelijke collectienamen afdwingbaar, zo is er bijvoorbeeld een lijst begrippen zijn die alleen meervoud kennen en ook niet altijd (is straatmeubilair meervoud of enkelvoud?) duidelijk (data wordt bijvoorbeeld binnen IT in enkelvoudsvorm gebruikt, maar daarbuiten als meervoudsvorm gezien) kan worden toegepast. Dit is belangrijk omdat voor het combineren van data uit verschillende bronnen daarmee dus alleen door een mens via bijvoorbeeld een mapping mogelijk is en hier ook interpretatieruimte kan ontstaan. Dat combineren speelt op het moment dat data al ontsloten wordt volgens (niet restful) APIs en andere databronnen. Het vereisen de meervoudsvorm maakt het gebruik en combineren van deze data daarmee dus ingewikkelder.

Los van bovenstaande probleem, speelt de meervoudsvorm voor collectienamen in OGC APIs minder. De OGC API specificaties bieden hier een uitweg: het aanroepen van de meervoud van collecties wordt expliciet gemaakt door dit alleen mogelijk te maken door deze beschikbaar te maken achter endpoints met een meervoudsvorm zoals /items of /tiles endpoint waardoor de OGC APIs voldoen aan de wens om sematisch betekenisvolle APIs te bieden. Hier kunnen we de gedachte achter de API design rule in stand houden dat de semantische betekenis van een API endpoint in het endpoint wordt uitgedrukt.

Heel concreet is dit met een voorbeeld te beschrijven:

We hebben deze keuze gemaakt omdat de BGT objecten in enkelvoud zijn opgenomen in het BGT Informatiemodel en dit op deze wijze daar goed bij aansluit (zie bijvoorbeeld Basisregistratie Grootschalige Topografie Gegegevenscatalogus BGT 1.2 3). De url van een collection eindigt op /items wat effectief meervoud is. Als we dat als resource beschouwen voldoen we aan de design rules en aan het BGT informatiemodel. Op deze manier hebben we getracht aan beide regels te voldoen.

Suggestie:

Voorstel om onderscheid te maken voor bestaande en nieuwe collectienamen. Voorstel is dit alleen voor nieuwe collecties te vereisen (MUST) en voor bestaande, breed gebruikte collectienamen te adviseren (SHOULD).

Als dit niet mogelijk is bovenstaande uitzondering toe te staan voor OGC APIs waarbij het probleem effectief niet voorkomt doordat de API zelf voorziet in meervouds-endpoints (denk aan {collection_name}/items).

[RoelvandenBerg]

Ter verduidelijking, na de richtlijn nog een keer met een collega door te spreken: in het voorbeeld van de OGC API is items inderdaad de resource en {collection_name} een id van een resource. Dus bovenstaande is correct. Daarmee is het voorbeeld dus niet volledig duidelijk . Voorstel om het voorbeeld aan te passen, dan wel uit te breiden. Het voorbeeld:

Example collection resources, describing a list of things:

https://api.example.org/v1/gebouwen
https://api.example.org/v1/vergunningen

Stel ik dus voor bovenstaande uit te breiden met:

Overigens is onderstaande ook correct. Hier is gebouw een instance van een api en items is de resource:

Example collection resources, describing a list of things:

https://api.example.org/v1/gebouw/items
https://api.example.org/v1/vergunning/items