RE: Proper use of Hydra IRI Template

On Friday, October 04, 2013 1:23 PM, Ryan J. McDonough wrote:
> On Oct 3, 2013, at 4:07 PM, "Markus Lanthaler" wrote:
> > On 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?

Yeah, I would say so.


> 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

Are you sure about that? I don't know JSON Hyper Schema well enough but in
HTML that functionality is simply missing. You have links with link
relations but there's nothing comparable for forms. So, how would a client
know which form to chose if there are several?


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

Well, the Atom Publishing Protocol for example defined the edit link
relation (which was a bad choice btw. because it resembles an operation and
not a relation) to express such an affordance. The only way to know what you
can do with such a link relation is to go and look up its definition. The
general definition in the IANA link relation registry isn't explicit enough
to do anything useful with it. So you need to go and look up how it is used
in the context of APP, i.e, RFC5023. Hydra brings all this in-band. You
define a property which acts as a link relation and specify in a
machine-readable way what the consequences of certain HTTP operations are:

{
  "@context": "http://purl.org/hydra/core/context.jsonld",
  "@id": "http://api.example.com/rels#edit",
  "@type": "Link",
  "title": "Refers to a resource that can be used to edit the link's
context.",
  "supportedOperations": [
    {
      "@type": "ReplaceResourceOperation",
      "method": "PUT"
    },
    {
      "@type": "DeleteResourceOperation",
      "method": "DELETE"
    }
  ]
}

I think this allows to build much more powerful clients. Furthermore, in a
lot of cases it is simpler to specify such operations directly on the class
instead of requiring to add such a self-referencing link to all resources.


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

Do you still find it awkward or do you see (at least some) value in being
able to have operations as well?


[...]

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

I think I misunderstood you because you referenced ISSUE-3. I assumed you
were talking about both JSON Schema (I agree with everything you just saidn)
*and* Hydra. In Hydra I disagree. Yeah, you couldn't reuse the complete API
description but you can reuse parts of it and definitely the whole Good
Relations vocabulary.


[...]

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

It should work but the console isn't up to date and doesn't parse the Link
header referencing your API documentation correctly yet. I can have a look
what went wrong if you send me a link to the document (feel free to send it
offlist if you aren't ready to share it publicly yet).



--
Markus Lanthaler
@markuslanthaler

Received on Friday, 4 October 2013 13:18:24 UTC