RE: Proper use of Hydra IRI Template

Ryan, you forgot to sent the mail to the mailing list, I'm cc'ing again and quote your full reply below

On Sent: Thursday, October 03, 2013 4:21 AM, Ryan McDonough wrote:
> Doh! I think I copy pasted the wrong way. Thanks! One thing that I
> think was tripping me up a bit was the relationship between hydra:Link
> and hydra:Operation. I grok'd that Operation is a specialized Link,
> but it was having trouble trying to describe a hydra:Operation that
> may need to use a URI Template. The /uri-template URI supports a
> variety of things.

In a sense you are right but I look at it from a slightly different angle. Typically I define links (instances of hydra:Link) as relationships between different resources. An operation on the other hand, describe the "affordances" a resource offers once you found it. Not sure whether this clarifies things or makes them even more confusing!?


> As far as the service goes, I maintain a Java library for processing
> URI Templates:
> 
> https://github.com/damnhandy/Handy-URI-Templates
> 
> I'm creating a service that allows you to interactively explain the
> structure of a URI Template and also pass values to it in order ensure
> a given URI template is correct. Basically, it's a tool to have folks
> test out the library as well as work as test bed to see how the
> library works in the context of an application.

Cool


> I have a JSON Hyper Schema that described the basics of the service here:
> 
> http://uri-templates.herokuapp.com/schema/uriTemplateStructure
> 
> It's simple, but should be able to see what I was trying to do. I
> quite like the way the JSON Hyper Schema describes links as well as
> the messages required by the server but there's a few things that
> bother me about it:
> 
> * JSON Referencing is a nice idea, but support is limited. The JSON-LD
> equivalent is quite obvious
> * Links are bound to the class and not an instance. This could make
> reuse problematic (I might be saying test to Issue #3 [1])

Could you elaborate a bit on this. I think you are conflating two things here. In Hydra links are definitely not bound to the class but to the instances. What can bound to classes (but also to instances) are operations. So you can either say that a specific resource supports a, e.g., POST or you can say that all resources of a specific type support it.


> * The structure description is simple, but it can't convey more
> expressive data types. Number and integer are too limiting.

Coupling on the structure is the most restricting point and all too often results in very brittle solutions.


> * No way to describe error messages when validation fails.
> * The spec seems to be in perpetual draft
> 
> I've started having a hard look at JSON-LD since I liker where it's
> going. Hydra is the next logical step.

Glad to hear that. Please keep us posted on your progress.


Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler






> Ryan-
> 
> [1] https://github.com/HydraCG/Specifications/issues/3
> 
> On Wed, Oct 2, 2013 at 3:14 PM, Markus Lanthaler
> <markus.lanthaler@gmx.net> wrote:
> > On Wednesday, October 02, 2013 4:29 PM, Ryan J. McDonough wrote:
> >> I'm in the process of trying to describe a service using Hydra and
> was
> >
> > Cool! Can you share a bit more about this service?
> >
> >
> >> having some trouble trying to express an IriTemplate for a given
> >> operation. I'm trying to describe a GET request with the following
> URI
> >> template and it's mapping:
> >>
> >> http://uri-templates.herokuapp.com/uri-template{?template}
> >>
> >> My initial version used JSON Hyper schema like this:
> >>
> >> {
> >>       "href": "/uri-template",
> >>       "rel": "about",
> >>       "method": "GET",
> >>       "enctype": "application/www-form-urlencoded",
> >>       "mediaType":
> >> "application/json;profile='/schema/uriTemplateStructure'",
> >>       "schema": {
> >>               "type": "object",
> >>               "properties": {
> >>                       "template": { "type": "string" }
> >>               },
> >>               "required": [ "template" ]
> >>       }
> >> }
> >>
> >> What I've got so far is this with Hydra is this:
> >>
> >> {
> >>     "@type": "hydra:IriTemplate",
> >>     "template": {
> >>         "template": "http://uri-templates.herokuapp.com/uri-
> >> template{?template}",
> >>         "mappings": [
> >>             {
> >>                 "@type": "IriTemplateMapping",
> >>                 "variable": "template",
> >>                 "property": "app:template",
> >>                 "required": true
> >>             }
> >>         ]
> >>     }
> >> }
> >>
> >> I don't feel I've got it right. Any pointers?
> >
> > I assume you have already seen the relevant section in the Hydra spec
> [1],
> > right? We should definitely add a more complete example to that
> section.
> >
> > Your example is more or less correct, you just used template twice
> which
> > isn't necessary. Here's how I would model it (using the "about" link
> > relation from your JSON Hyper-Schema):
> >
> > {
> >   "about": {
> >     "@type": "hydra:IriTemplate",
> >     "template":
> > "http://uri-templates.herokuapp.com/uri-template{?template}",
> >     "mappings": [
> >       {
> >         "@type": "IriTemplateMapping",
> >         "variable": "template",
> >         "property": "app:template",
> >         "required": true
> >       }
> >     ]
> >   }
> > }
> >
> >
> > [1] http://www.markus-
> lanthaler.com/hydra/spec/latest/core/#templated-links
> >
> >
> > HTH,
> > Markus
> >
> >
> > --
> > Markus Lanthaler
> > @markuslanthaler
> >
> >
> 
> 
> 
> --
> Ryan J. McDonough
> http://www.damnhandy.com

Received on Thursday, 3 October 2013 20:07:54 UTC