search

linkedfactory / specification

Documentation of the LinkedFactory data formats and APIs.
0 stars 0 forks source link

[API] Remove items and properties parameters in the /values endpoint #2

Open ForcamPB opened 1 year ago

ForcamPB commented 1 year ago

The parameters items and properties should be removed to make the endpoint simpler. Instead the item and property query could be used multiple times like /values?item=aaa&item=bbb.

kenwenzel commented 1 year ago

Thank you for bringing this up. The support for repetition of HTTP parameters seems to depend on the programming framework: https://stackoverflow.com/questions/11621477/using-duplicate-parameters-in-a-url

Therefore it may be hard or even impossible to achieve the desired effect in certain environments.

Maybe we could also just allow item and property to contain multiple space-separated values instead of using the plural forms?

ForcamPB commented 1 year ago

I would favour a solution without the plural form. Because during implementation I was not sure what to do when for example both variants are set. And I couldnt just mark the singular variant as required, because it can be left out when using the plural variant. In the end I merged the singular and plural values and required that at least one value must then be present.

Also it seems to me that most frameworks use comma-separated values and not space separated values. At least comma separation appeared a lot when browsing stack overflow.

E.g. our framework supports multiple appearances of the same parameter and comma-separation out of the box: https://www.baeldung.com/spring-request-param#mapping-a-multi-value-parameter

kenwenzel commented 1 year ago

I would also opt for the singular forms. But comma separation is not possible as a comma (,) is a valid character within URIs/IRIs.

Related question: https://softwareengineering.stackexchange.com/questions/386944/unambiguously-represent-separator-in-a-string-containing-an-uri

ForcamPB commented 1 year ago

In that specific case it doesn't matter if we use , or space for separation. When it comes to special characters the standard is not very distinct. So clients should encode both characters to ensure correctness. , should be encoded with %2C and space with %20 or a +.

So from this perspective it doesn't matter if the encoded URL contains ?item=aaa%2Cbbb or ?item=aaa%20bbb