Re: Proper use of Hydra IRI Template

On Oct 3, 2013, at 4:07 PM, "Markus Lanthaler" <markus.lanthaler@gmx.net> wrote:

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

2nd time I've done that :( Thanks for replying back to the list!

> 
> 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!?


This clarifies the distinction between hydra:Link and hydra:Operation. If were to draw similarities to frameworks like Symfony, JAX-RS, etc., this is like defining a resource with a URI that can handle different HTTP methods. I that is an apt comparison?

If that is correct, I'm not so sure that it makes sense from a client perspective. Other models like HTML and JSON Hyper Schema don't make this distinction and it's still equally as functional. I think most in the REST community who are currently favoring things like JSON Schema, HAL, Collections+JSON, etc., may share a similar view. HTML does this as well. The link and it's relation is the affordance. The JSON Hyper Schema model only has support for links which may be read-only or they may modify some piece of data on the server. The simplicity of the JSON Hyper Schema model is appealing, but I'm willing to bet I'm missing something. 

While I find this slightly awkward now, I'll reserve judgement until after I get a service and client up and running before I comment on this further. 

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

Maybe I'm wording my concerns wrong, but here's where I have some doubts: let's say you wanted to reuse my JSON Schema to describe a URI Template and/or the request of a URI Template expansion. The Links defined in the JSON Hyper Schema will work for my service but you may not like my the way my URL scheme suggests a particular implementation direction. The question is are you stuck with my links because you used my schema or can you overload the links from my schema but describe the data the same way? To put it another way: we have two online stores. We both describe our data using the Good Relations vocabulary. More than likely, both stores wold have different APIs even though they describe data the same way. 

My concern with JSON Hyper Schema is that the links appear to dictate how a given service should describe it's links/operations as well as it's data. 

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

I'll have something functional up sometime next week and I'll you have at it. BTW, does the Hydra console support remote descriptors? I tried to see if it would load a remote hydra document and it juts hung. 

> 
> 
> 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 Friday, 4 October 2013 11:23:09 UTC