RE: Hydra scope

On Friday, May 09, 2014 10:19 PM, Chris Chapman wrote:
> > 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 :)

Great. Welcome on board!


[...]

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

OK


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

Right. The only thing that may add some value is is hydra:Link and hydra:Resource to distinguish between links and dereferenceable resources and just identifiers that aren't intended to be dereferenced. But that's more a theoretical thing than of much practical benefit in your case.


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

Interesting.. could you illustrate this with a simple example? It's not something that is seen often in the wild AFAICT.


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

OK. What's not very clear to me at the moment is whether you manipulate the server's resource state or send some form of "commands" or "method calls" (if you want) to the server!? The way you described it above suggests the latter.


[...]

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

As you know, that's in fact one of the first issues I raised:

  https://github.com/HydraCG/Specifications/issues/2

... but so far you are the first one to mention this. The reason it is called Operation is because in the end it describes a HTTP operations (or requests). I have no strong opinion on this and would like to hear other peoples thoughts on this.


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

All good points.

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

Would you then also rename the properties "operation" and "supportedOperation" to "action" and "supportedAction"?


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

The decision was to optimize for that, you can of course also embed them directly into your representations.


> 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

It basically provides you a map which shows you all possible routes and state transitions. Which are available, has to be determined at runtime.


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

Right, in most cases Web APIs are quite uniform and thus optimizations like this make a lot of sense IMHO.


> > > 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 :)

Right :-) In the end, the semantics have to be somewhere. You can either create specific media types and link relations for that, or have a generic media type with a well-defined processing model and fill it with concrete semantics by means of a vocabulary. I think the latter is more flexible and thus easier to scale as it separates concerns better and is easier to reuse. You can't mix and match media types the way you can mix and match vocabularies.


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

That's great. There are a couple of issue we need to resolve. I've sent out concrete proposals for most of them a little while ago:

  http://lists.w3.org/Archives/Public/public-hydra/2014Apr/0050.html

If you could have a look at that mail and provide some feedback would be helpful. When we got those basic things right, we need to improve tooling support and work on a couple of nice showcases. Currently there only exist a few prototypes I've built a while ago (HydraConsole, HydraBundle). Other than that, we certainly need to clarify and extend the spec so that it is simpler for newcomers to understand. A nicely designed homepage would also help to get more people interested.

What things would you be interested in helping with?


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


--
Markus Lanthaler
@markuslanthaler

Received on Monday, 12 May 2014 14:59:35 UTC