Re: Filters as views (ISSUE-45)

Hi Ruben,

in your original proposal you suggested hydra:filter, which did not spell out a query syntax either, but it defined one in prose. So I do not think your original interest was to spell out the query syntax to the machine. I really try to make things less complicated for hydra, not more.

In my suggestion

"urlSyntax": "tpf url syntax uri"

was not supposed to say it is a tpf api, only that the URI syntax is the one described by tpf. We could also call it "simple hydra query syntax", describe it in the hydra spec and use a hydra URI for it, for that allows you to describe tpf in terms of hydra and not the other way around. You certainly agree that self-descriptive messages as a ReST constraint always implied that certain external conventions can be invoked as part of the self-description, e.g. by mime-types or profiles, so we would absolutely be self-describing.

The difference between hydra:filter and this suggestion is really only that urlSyntax allows to plug in external url syntaxes, whereas :filter would have been restricted to tpf queries. BTW odata and opensearch are not really a good fit for uritemplates. I like Tomasz's idea to have pluggable filtering mechanisms.

Can you line out a use case where the machine requires a detailed, case by case description of the query syntax with allowed comparison operators, allowed usage of AND and OR etc., where no human is involved? What I can see is that an application could present a query builder UI for a human, but otherwise?

Best regards,
Dietrich

Am 15.02.2016 9:57 nachm. schrieb Ruben Verborgh <ruben.verborgh@ugent.be>:

Dear all,

We're making things too complicated.
This thread is not about describing every little detail,
but about deriving views of collections.

>>> "urlSyntax": ... one of TPF, opensearch, odata ...
>> 
>> Then we lose the self-descriptiveness and we're back to square one.
>> 
> 
> No, we're not. Hydra already provides more API description facilities than any other hypermedia media type I know.

I need something more than an IRI saying "this is a TPF API", to describe a TPF API.
Otherwise, I might as well just not describe it at all and just say "it's a TPF API“.

> But you will never be able to describe all hypermedia operations/links in a machine-readable manner. At least not in the sense that machines can "understand" it.

That's not the goal; the goal is to reduce the API
to symbols the client knows and can manipulate.

The question is: how do we choose that set?
It should not be too complex, but not too simple either.
Too simple means every use case is a one-off.
Too complex means nobody will use it.

A minimal set of symbols includes for me
at least the possibility to describe
how a form creates a view from a collection
for basic combinators such as AND and EQUALS.

If we can't say in Hydra that
“this view chooses items of the collection
that have equal values to your input”
than we cannot do a lot with Hydra.

If we do allow that in Hydra,
we should make that mechanism extensible
to support other ways of defining views in the future.
Otherwise, it's again a one-off.

That's the path that I want to choose.

> However there's great value in machine-readability where all of the API metadata is processed at runtime.

That value is limited if the metadata is simply "this API is TPF",
which what Dietrich proposes comes down to in the end.

(Yes, there was more complexity to his proposal than that,
but it comes down to having very specific constants
such as "TPF" pre-coded. I'm against that. TPF is too specific.
But TPF can be expressed with more generic components.)

> This is what hypermedia is all about and not about making the API client understand what it means to perform an operation, which reserves a seat at a concert.

World-changing operations are a different class altogether.
We are talking about *simple*,
read-only application state transitions here.

So let's keep the discussion focused:
explaining to a client in what way exactly
it can create a view from a collection.

Best,

Ruben