Re: Hydra scope

Hi Markus,

Replies inline:

----- Original Message -----
> From: "Markus Lanthaler" <markus.lanthaler@gmx.net>
> To: public-hydra@w3.org
> Cc: "Chris Chapman" <chris@pentandra.com>
> Sent: Thursday, May 1, 2014 3:55:25 PM
> Subject: RE: Hydra scope
> 
> Hy Chris,
> 
> On Thursday, May 01, 2014 9:54 AM, Chris Chapman wrote:
> > I've spent the past day looking into Hydra and am very impressed with it
> > and the JSON-LD
> > movement.
> 
> Great. Thanks. In that case, you should probably join our community group at
> 
>     http://www.w3.org/community/hydra/
> 
> :-) You don't have to be a W3C member of anything, but you need to get a
> (free) W3C account at [1] if you don't have one yet.
> 

Joined :)

> 
> > I am trying to determine whether Hydra would be a good fit for a project,
> > and I would love
> > some feedback.
> > 
> > My requirements
> > 1. Combine the best of linked data and REST (self-describing messages),
> > ideally using
> > JSON-LD.
> 
> This is exactly what we are trying to do.
> 

Good.

> 
> > 2. Complex, custom state transitions (not CRUD). State transitions are
> > driven by use cases
> > rather than data relationships.
> 
> Could you please explain in a bit more detail what you mean by the second
> sentence?
> 

Yes. We're building a event-sourced CQRS system [1,2] involving two APIs, one for getting public read-only data out of the system (query API), and one for making changes to the system (command API). Just to avoid confusion, the term "query" is used here in a high-level way to mean "getting data out of the system". It is still a REST API, not something like a SPARQL endpoint.

The query API is similar to many of the APIs that are in existence right now: the structure of the API closely resembles the structure of the data that the system was designed to curate (the domain model, application data, or whatever you want to call it). You can follow your nose through the data the system is about. Plain (old) JSON-LD is sufficient here (I think...) because there are no unsafe state transitions.

On the command side of our system, it made more sense to group things around use cases and tasks (commands). The command API is structured around what you can _do_ with the system, not the structure of the application data, though it ends up looking somewhat similar. You follow your nose through use cases and tasks, which follow a hierarchical form, from more general to more specific, as you move through a process. A resource generally represents a use case, from the client's perspective, the tasks (or commands) it can send to the system that have to do with the use case, any related queries that would be helpful in accomplishing the use case, any related use cases (oftentimes sub-resources), and some application data (if any) that has to do with the use case. In the end, we want a graph of use cases that are related to each other in various ways, perhaps using domain-specific ontologies. 

[...time passes...]

After thinking about it more, I think that while there are conceptual differences in the design of the API, there is little technical difference between the two approaches. Either way, we have "the simultaneous presentation of information and controls" [3]. 

> 
> > 3. Links for possible state transitions need to be dynamic, meaning the
> > server decides which
> > "next" transitions are appropriate with each server response.
> 
> OK. That's trivial. You just include or exclude those links in your
> responses.
> 

This makes more sense now. (See next response)

> 
> > >From what I understand of Hydra so far (please correct me if I'm off
> > >base):
> > 1. Hydra is geared primarily towards hypermedia CRUD APIs driven by data
> > relationships.
> 
> Nope. It works for completely arbitrary operations. The predefined CRUD
> operations are just there as examples, in most cases you would either want
> to define your own or, even better, use existing ones such as the ones from
> Schema.org's Action subtree [2]. This will be clarified in a future version
> of the spec.
> 

I have to admit, when I was first reading the hydra spec, and it was talking about Classes, Operations, and Properties, I started thinking object orientation, and stumbled into that hole. It took a bit more reading and studying the demo app to correct that misconception and to realize that Operations are just descriptions of unsafe HTTP requests, and are not attributes of Classes, siblings of Properties.

I think the term "Operation" is overused, ambiguous, and has some RPCish connotations, in the sense that RPC tries to encapsulate the network, hiding it from the application in a black box. REST wants to work within the constraints of the network, exposing the glory of all the protocol and application semantics to the client, so the client can make decisions with knowledge. Why not use a term that is a little less abstract, such as "action"? The Collaborative International Dictionary of English defines action as "the effect of power exerted on one body by another", preserving, in this context, the semantic understanding that one agent (the client) interacts with another agent (the server) over the web. The client recommends changes, but inevitably it's up to the server to accept them or not. Also, Action implies change, supporting the idea of an unsafe HTTP request, or a request that manipulates the server's resource state. "Action" is also more in line with what Roy Fielding said, that hypertext is "the simultaneous presentation of information and controls such that the information becomes the affordance through which the user obtains choices and selects actions" [3].

I noticed that you have an issue about this already [4], but I would recommend changing the term Operation to Action for the above reasons, and not because schema.org, Siren, or Activity Streams already use the term.

> 
> > 3. All possible protocol and application semantics (operations, etc.) are
> > known by the client
> > ahead of time (in the app's context). The hydra:Class determines which of
> > the operations are
> > deemed appropriate in the current situation. For CRUD would work really
> > well, but for a
> > more complicated non-CRUD API this would fall apart, requiring the client
> > to understand
> > business rules to make appropriate decisions about transitions, potentially
> > doing away with
> > HATEOAS. :(
> 
> The client obviously needs to "understand" the application domain (products,
> orders, etc.) and Hydra (operations, links, perhaps also collections and
> templated links). Operations can not only be bound to classes but also to
> links, i.e., properties or link relations if you want. Furthermore, you can
> include them directly into responses which would be more or less the
> equivalent of including forms in an HTML document. Hydra was specifically
> created for hypermedia-driven Web APIs. So, if you think we violate the
> HATEOAS constraint, you should tell us as that would be a serious issue.
> 

Now that I understand that Operations are about the protocol and not intrinsic to a hydra:Class (see previous comment), this clarifies things immensely.

In your paper {Hydra: A Vocabulary for Hypermedia-driven Web APIs}, you mention that one design decision was to group the hypermedia controls into one separate document. So this document, the hydra:apiDocumentation, describes all of the possible state transitions (among other things) of the API. Our initial REST API returned an empty form when doing a GET request on a command resource. The user (via the client) would then fill in the form and do a POST with the filled-in form data to the same resource. Either way, I don't think this violates HATEOAS, though Hydra has the advantage of being less chatty because it describes all the Operations ahead of time, once. 

> 
> > At first glance, it doesn't seem that Hydra would be a good fit (or am I
> > seeing things
> > wrong?). If not, do you feel that this would be within the scope of a Hydra
> > extension or
> > would it fit better in a separate project (or has work been done in this
> > area by someone
> > already? I would rather collaborate than duplicate efforts).
> 
> I think you got it partly wrong which without doubt has to do with the
> current state of the documentation. From the limited information you
> provided about your project, I think Hydra would be a great fit. Please
> don't hesitate to ask further questions or propose extensions etc. Let's see
> where we can take this together and welcome on board :-)
> 

I first heard of Hydra at the W3C workshop on annotations last month where Gregg Kellogg gave a presentation on Hydra for Web Annotations. I put Hydra on my list of technologies to look into. For a while we've been looking for ways to develop APIs, based on REST principles, with the primary goals of enabling clients to connect to various APIs in open and flexible ways, without breaking when the server implementation changed (essentially experimenting with various HATEOAS approaches). We had been going down the media-type path until we found JSON-LD, and realized that an API based on a vocabulary/ontology could be much more expressive and flexible than one based solely on media types. Apparently, we were not alone in thinking that :) 

So, we see a lot of good in what you have done so far with Hydra. We'd love to work together. I get the impression that Hydra is still in gestation stage. What things do you feel are lacking, and what is your time frame for a definitive release of the spec? How do you need help? 

Chris

> 
> Cheers,
> Markus
> 
> 
> [1] https://www.w3.org/accounts/request
> [2] http://schema.org/Action
> 
> 
> --
> Markus Lanthaler
> @markuslanthaler
> 
> 
> 

[1]: http://martinfowler.com/bliki/CQRS.html
[2]: http://martinfowler.com/eaaDev/EventSourcing.html
[3]: http://www.slideshare.net/royfielding/a-little-rest-and-relaxation (slide #50)
[4]: https://github.com/HydraCG/Specifications/issues/2

Received on Friday, 9 May 2014 20:19:26 UTC