RE: TemplatedLink

On Thursday, July 11, 2013 11:28 AM, Matthias Lehmann wrote:
> I wonder, how hydra:TemplatedLink should be used.
> 
> The way, I understand it is this:
> 
> Some API respone:
> 
> {"@context": "/Flubber.jsonld",
>  "@type": "Flubber",
>  "flup": "schwubb",
>  "link": {"template": "http://example.com/flups/{flup}",
>               "mappings": {"variable": "flup", "property": "flup"}}
> }

That's correct. The "property" is a URL though. So in your example, it would
probably correspond to the flup property. So your context needs to contain
the following definition for property

  "property": { "@id": "hydra:property", "@type": "@vocab" }

If you wouldn't set the type to @vocab it wouldn't be interpreted as URL;
setting it to @id wouldn't work here either as that would interpret flup as
document-relative URL.


> API-description:
> {
> [..]
> "supportedClasses": [
>  {
>     "@id": "Flubber",
>     "supportedProperties": [
>        {
>           "property": {"@id": "link", "@type": "hydra:TemplatedLink"}
>        }
>    }
> [..]
> }
> 
> This looks very verbose. Is it necessary to have a
> hydra:IriTemplateMapping with a hydra:IriTemplate?

It's true that it is quite verbose and I have been thinking about allowing
to set the mapping directly in the API description but I came to the
conclusion that the template probably varies a lot and thus that wouldn't
help much. Maybe setting default mappings that can be overridden by embedded
mappings would make sense though!?


> Are there arguments
> against having variabale names mapping to properties with equal name
> by default? So in the example above, the mappings could be omitted.

Well, strictly speaking they almost never have the same name. The variable
name is a short string whereas the property is a full URL. It just happens
that JSON-LD allows you to compact URLs to nice, short terms. You would have
problems achieving the same in all other serialization formats. JSON-LD is
preferred serialization format for Hydra but not the only one supported. You
could just as well use Turtle if you prefer.


> A TemplatedLink as I understand it is only useful, if it can be
> applied to several items.

Yeah, the other case where it is useful is when the server doesn't have
enough information to construct the full URL. Query URLs are an example for
that. Obviously the server doesn't know the query the client wants to
execute so it just provides a URL template which the client can fill with
the query to construct the full URL.


> I think it is very common to have a API
> response contain a collection of JSON objects at some place of the
> JSON structure. I wonder, how I can say, that a TemplatedLink should
> be used for a distinct set of objects. Did I miss something, or is
> this still missing?
> 
> I could image something like this:
> 
> { [..]
> "items": [
>    {"name": "foo"},
>    {"name": "bar"}
>   ]
>  "link": {"template": "http://example.com/flups/{name}", "appliesTo":
> "items"}
> }

IMO this clearly falls into the realm of the client's (or server's) business
logic. What should a client do with such a link if the only thing it
understands would be Hydra? It would just know that there's a link template
and that there are a couple of objects that can be used to fill that link
template. It wouldn't however understand what that link is for. Thus I
believe, this should be defined at the application level. So a client
understanding that specific template link, would also know where to look for
the data to fill the template. Does that make sense?

In the example above I would typically include the link directly. It reduces
complexity quite a bit and has the advantage that even JSON-only clients can
access the link; GZIP will take care that the payload won't grow too much.


> I am still trying to grok, how a Hypertext-API could work. We have a
> API which quite often returns collections of items, each of which has
> a set of links or actions. One approach is to make it all explicit and
> have every link as a property of each item. This is easy to use, but
> it bloats the response.

Did you compare the size differences after gzipping the responses? I would
expect that the difference is quite small.


> So templated links look like a good
> alternative. But I don't see, how these work without "out-of-bounds"
> information of how to apply them.

Well, if you define your own property "appliesTo" and include that in the
responses as you did above I wouldn't consider it as out-of-band knowledge.
The client has to understand the (templated) link(s) anyway. That's not much
different from requiring the client to also understand "appliesTo".

I really enjoy these discussions because it helps to evaluate how Hydra
helps for a concrete, real-world use case. Can you share a bit more about
what you need to achieve or can't you talk about that yet? I'm mostly
interested in the high level functionality the API you are building has to
support.


Thanks,
Markus



--
Markus Lanthaler
@markuslanthaler

Received on Thursday, 11 July 2013 10:06:27 UTC