search

Geonovum / KP-APIs

26 stars 40 forks source link

query-parameters en velden waarop gefilterd kan worden: overnemen vanuit json:api? #307

Open mevdschee opened 5 years ago

mevdschee commented 5 years ago

In 4.7.1 staat:

API principe: Filter query-parameters zijn gelijk aan de velden waarop gefilterd kan worden

Maar json:api schrijft voor dat de parameter "filter" gebruikt wordt voor dit doeleinde (zie: https://jsonapi.org/format/#fetching-filtering). Er is afgeweken zonder argumentatie.

Ook zou ik deze vorm niet aanraden: De veldnamen van de data worden nu ook als parameters gebruikt, maar deze namespace is al deels vergeven aan andere functionaliteit (sorteer, zoek, etc.).

dvh commented 5 years ago

json:api was nooit het uitgangspunt (dat had het wat mij betreft overigens wel mogen zijn).

Wat betreft de namespace denk ik dat sorteer, zoek, etc. anders genoemd zouden moeten worden. Om precies dezelfde reden prefixen we niet-data-collecties met een underscore, dat zouden we hier ook kunnen doen: _sorteer, _zoek, etc.

mevdschee commented 5 years ago

json:api was nooit het uitgangspunt

Er zijn wel veel dingen uit overgenomen, waarom deze niet?

dvh commented 5 years ago

Volgens mij is dat toeval :)

mevdschee commented 5 years ago

Ik vind het jammer dat de discussie nu niet over inhoudelijke zaken gaat.

De standaard maakt hier een rare keuze, die afwijkt van een standaard die iedereen die een json api maakt kent. Ik stel ter discussie dat er wordt afgeweken. Ik ben benieuwd naar de inhoudelijke motivatie van deze beslissing en niet naar het proces.

dvh commented 5 years ago

Volgens mij heeft dat heel veel met elkaar te maken. Zoals het nu beschreven is, is het van scratch zelf verzonnen, dus zonder weet van de json:api standaard. Inhoudelijk dekt de huidige guideline de usecases die op dat moment bekend waren. Met de kennis van nu hadden we mijns inziens beter json:api kunnen overnemen, zo niet alsnog de syntax opnieuw te bekijken.

mevdschee commented 5 years ago

@dvh Goed punt, dat maakt het proces relevant, dankjewel.

mrtn78 commented 3 years ago

In het normatieve deel van de ADR is expliciet gekozen voor toepassing van de OpenAPI specification. (API-16). Daarmee kan m.i. dit issue worden gesloten

mevdschee commented 3 years ago

In het normatieve deel van de ADR is expliciet gekozen voor toepassing van de OpenAPI specification. (API-16). Daarmee kan m.i. dit issue worden gesloten

@mrtn78 De OpenAPI spec schrijft niet voor welke parameters waarvoor gebruikt worden, alleen hoe je ze documenteert. Een OpenAPI beschreven API kan de json:api standaard volgen, maar ook niet. Ik stel ter discussie dat beter de json:api standaard gevolgd kan worden (voor parameter naming). Misschien kan je aangeven wat jouw opmerking met dit onderwerp te maken heeft?