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

[RoelvandenBerg]

Paragraaf nummer:

API Design rule #54

Korte omschrijving:

-edit-
Ik pas deze tekst niet aan, maar mijn reactie hieronder geeft nog iets concreter aan waar dit verbetervoorstel voor dient. API Design rule #54 kan naar mijn idee verwarrend zijn omdat er in het voorbeeld en de tekst geen duidelijk onderscheid wordt gemaakt tussen resources en resource identifiers. Het voorbeeld is opzich correct, maar kan verwarring veroorzaken op het moment dat de resources (bijvoorbeeld gebouwen) zoals in het voorbeeld de positie van resource identifiers innemen (zoals bijvoorbeeld in OGC API collections) . Verzoek is om dit expliciet te maken. Waarbij de regels over meervoud betrekking hebben op de resources.
-edit-

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]

-edit- onderstaande reactie is d.d. 18-12-2024 aangepast ter verduidelijking -edit-
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 (resource identifier). Dus bovenstaande is correct voor OGC APIs (en vergelijkbaar opgebouwde apis). Daarmee is het voorbeeld in API-designrule 54 dus niet volledig duidelijk. Verwarring kan ontstaan doordat de concepten van "resource" en "resource identifiers" niet expliciet worden benoemd. 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 de resource identifier, oftewel een instance, van de resource collections en items is de resource die de features van de gebouw collection beschrijft:

Example collection resources, with resource identifiers being accessed through resources, describing a list of things:

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

[RoelvandenBerg]

Het probleem wordt overigens nog duidelijker als er gekozen wordt voor resource identifiers die (om wat voor reden dan ook) geen semantische betekenis hebben als UUIDs of integers of bijvoorbeeld IMRO-codes.

[joostfarla]

De design rule /core/naming-collections (voorheen #54) beschrijft dat collection resources in de meervoudsvorm geschreven dienen te worden.

Voor de OGC API Features standaard geldt de volgende URL structuur:

/collections/{collectionId}/items/{featureId}

Hier ontstaat mogelijk verwarring, omdat met een collection hier iets anders wordt bedoeld, namelijk een "feature collection". /collections is dus in feite een collection resource voor feature collections en /collections/{collectionId}/items is een collection resource voor features (binnen de feature collection).

In ADR termen komt deze structuur neer op:

/{collection}/{singular}/{subcollection}/{singular}

Zowel collections als items is hier in de meervoudsvorm geschreven, dus daarmee wordt strict genomen netjes voldaan aan deze design rule. Voor singular resources is er geen design rule die iets zegt over naamgeving, dat mag van alles zijn (UUIDs, IMRO IDs, type namen, etc.). Bij voorkeur dienen wel de informatieve naming conventions gevolgd te worden.

Los van bovenstaande, blijven de genoemde argumenten valide, namelijk:

1. De Nederlandse taal kent diverse speciale gevallen, zoals in de uitleg van @RoelvandenBerg beschreven. Hier is in de design rule geen rekening gehouden. Het voorstel is om dit expliciet te beschrijven en gebruik van afwijkende vormen voor deze situaties toe te staan.

2. Wanneer API specificaties automatisch worden gegenereerd (bijvoorbeeld vanuit een MIM-model) kan niet automatisch een correcte meervoudsvorm bepaald worden. Hier zal dus altijd een mens (of AI) aan te pas moeten komen, wat niet altijd wenselijk/realistisch is. We zouden kunnen overwegen om hiervoor een uitzondering op te nemen. De implicatie hiervan is dan wel dat deze design rule minder eenduidig en meetbaar wordt, iets wat vanuit standaardisatie-perspectief mogelijk onwenselijk is.

3. Er ontstaat een interoperabiliteits-uitdaging wanneer collectienamen afwijken van de formele begrippen / informatiemodellen. Echter, ook bij de enkelvoudsvorm spelen dergelijke uitdagingen, omdat er altijd een conversie plaatsvindt van een term naar een URL-vriendelijke identifier. De originele term kan speciale karakters bevatten, zoals spaties, koppeltekens en diakrieten, en er kan specifiek hoofdlettergebruik in voorkomen, bijvoorbeeld bij afkortingen (bijv. IMGeo-object of Structuurvisieplangebied_G). Hier zijn geen eenduidige conversie-regels voor gespecificeerd. In de ideale situatie wil je een gestandaardiseerde manier om van een model-element (bijv. een MIM objecttype in een logisch informatiemodel) naar een resource URI te komen. Dit is een thema dat al vaker voorbij is gekomen (o.a. bij de werkgroep orkestratie), en waar ook al wat ideëen voor zijn uitgewisseld. Een oplossingsrichting zou kunnen zijn om een standaard locatie en structuur te hebben voor een mapping van model-element naar API-resource namen. Dat is niet alleen handig voor de conversie naar de resource URI, maar hier kunnen ook andere karakteristieken van de API in opgenomen worden (bijv. hoe wordt omgegaan met generalisatie in het model). Zo'n mapping zou in de API specificatie kunnen zitten (middels een extension) of zou aangeboden kunnen worden via een introspectie-endpoint. Daarnaast zou het voor de toekomst wellicht ook interessant zijn om dit onderwerp aan te kaarten bij de MIM-werkgroep, zodat een URL/DB-vriendelijke (meervouds)vorm mogelijk een plek zou kunnen krijgen in de MIM-standaard.

Ik neem per mail nog even contact met jullie op om dit nader te bespreken!