Re: Filters as views (ISSUE-45)

Hi Ruben,

This discussion started from the semantics of collection filtering and indeed drifted far into templates, parameters and mappings. I think it's for good reason, because we generated an inconsistency and tension in how templates work. My proposal for extensibility is to create a hierarchy of templates and/or template variable mappings to cater for various cases.

Here are some examples

1. Collection filter
This is what you're after and much like most examples to date

{ 
  "@type": "FilterMapping", 
  "variable": "name",
  "property": "schema:firstName"
}

2. Collection controls
For example paging, as suggested by Karol

{ 
  "@type": "CollectionPagingMapping",
  "variable": "p",
  "property": "hydra:page"
}

3. Closed set of allowed input values
Type defines valid datatype and allows extension for additional constraints (could also be SHACL or custom)

{ 
  "@type": "TypedParameterMapping",
  "variable": "age",
  "datatype": "xsd:Integer",
  "minValue": 18
}

4. Free text param of unspecified representation semantics

{ 
  "@type": "FreeTextFilter",
  "variable": "query"
}

5. Mix and match
You could constrain collection filter by mixing multiple mapping types

{ 
  "@type": [ "FilterMapping", "TypedParameterMapping" ], 
  "variable": "name",
  "property": "schema:firstName",
  "datatype": "xsd:String",
  "maxLength": 4
}

6. OData mapping
Maps to multiple variables. Similarly there could be a SPARQL mapping as proposed by Pierre-Antoine

{ 
  "@type": "ODataMapping", 
  "variable": [ "name", "lastName" ]
  // not sure what OData would need
}

Such design can't impose any default behaviour when the template variable mapping is untyped and so be it. There is no sensible default behaviour. In such case the client would have to ask user for any input and hope for the best :)

It is also important that the client would have to be aware of any possible mapping type. Hydra could define a few but allow custom ones (such as the schema:GeoRadius for example). Client would have to be implemented in a plugin manner so that they can be extended with awareness of those custom mappings.

I hope I make sense and it's focused enough :)

More replies inline.

Cheers and good day,
Tom

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

I agree, but "deriving views of collections" is just on specific case of views and by extension templated links. We cannot let the design decisions for a more specific case spill over to the more general.

>> 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.

Agreed. We need to define primitives and build upon those.

> 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.
> 

>From the bottom up the most fundamental are:
1. IRI template
2. views and templated links (which are similar)
3. template variable matchings

> 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.
> 

This is a minimal set for filtering views but not views alone.

> 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.
> 

Precisely, but when focusing on collection filter views, we should keep in mind the it is already an extension of a more primitive view mechanism we have only half-baked. The important part is not to let collection filter-specific decision affect view in general. This will help us design a simple yet extensible mechanism. It's somewhat like the Open-Closed Principle.

>> 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.)

Why not allow that? Wouldn't an OData view be possible along a Hydra view?

> 
>> 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.
> 

Right, but that's not what I meant. I wanted to give an example where the client needs intimate knowledge about processes and other
out-of-band information. Such is the schema:geoRadius example, where the client must understand all those terms up-front. Much like it would have to understand OData or SPARQL shall we have them as one possibility to describe filters.

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

I think we need the basic structure first and define the extensibility model. Only then can we talk about implementing a more specialized use cases.

Received on Tuesday, 16 February 2016 10:17:10 UTC