Re: Hydra scope

Hi, Markus,

Replies inline.

Chris Chapman
Pentandra


----- Original Message -----
> From: "Markus Lanthaler" <markus.lanthaler@gmx.net>
> To: public-hydra@w3.org
> Cc: "Chris Chapman" <chris@pentandra.com>
> Sent: Monday, May 12, 2014 8:58:59 AM
> Subject: RE: Hydra scope
> 

[...]

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

Answered below.

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

I've learned that REST, while having many constraints, opens up many new ways of looking at things. It has been said that "a resource is not the thing" [1], though it is something with an identity that needs to be discussed. Representations somehow represent that thing and can be transferred over the wire. "URIs are identifiers of resources. GET is a request for a representation of the current state of the identified resource" [2]. While this is all very abstract, it provides for a lot of flexibility and opens the doors for more than one way of looking at the world. 

If you perform a GET action on my chair, you could get back a representation of its make, model, color, cost, and current depreciation. Many of the "normal"  REST APIs look like this today. This structural approach is very useful, but, in my opinion, somewhat boring. If I looked at the chair from a functional point of view, I could design my chair API so that when I performed a GET action on my chair, I received a representation of the current things my chair could do, with controls that allowed me to do them. For example, I could use my chair to sit in (as long as the server knew that the chair is currently empty), or use as transportation (as long as the server knew the chair had wheels, some sort of propulsion system, etc). The server would include a link and instructions on how to transition the chair into that new state. The client (e.g. the user, or chair sitter) would then freely select the action it wanted to perform. This is what I've referred to above as a "command": the action to transition the resource into a new state. Simply put, in this paradigm, the representation of a resource is a finite state machine where the available transitions are presented by the server and activated by the client.

I can take it a step further and say that while there are many things to do with a chair, common use cases can be grouped together, for example:

Normal things to do with a chair:
* Sit in
* Roll around in (if it has wheels)
* Swivel in (if it can swivel)
* Stand on

Administrative things to do with a chair:
* Reupholster
* Grease wheels
* Vacuum the cushions
* Clean
* Dispose of

These two groups of use cases can be thought of as different representations of my chair, available at different URLs. 

Using the above example, my normal chair representation could be available at:

http://www.example.com/myoffice/chair 
(I'm logged in, so this example system knows which chair is mine, and gives me the information and controls I need to manage it for my own purposes)

If the system let me manage other people's chairs as well, they could be available at:

http://www.example.com/office/1/department/it/office/markus/chair

Then this chair would obey my every command, much to your chagrin ;)

If my job was a facilities manager, I would have access to the chair's administrative use cases, available at:

http://www.example.com/administration/office/1/department/it/chairs/2343242

And could take the chair out of service for maintenance (cleaning), though I may not have access to the chair's normal use cases. If my server's URL structure was hierarchical in nature, I could check for proper authorization high up in the hierarchy, making it easier to enforce authorization for groups of use cases at the server. In this example I would only have to check once to make sure only administrators had access to <http://www.example.com/administration> and all sub-resources.

Of course all of this is server-side implementation detail and dependent upon the actual needs of the system.

Using domain-specific ontologies/vocabularies (like the functional ontology of a chair, for example) and JSON-LD/Hydra would make this approach really interesting for discoverable, dynamic web APIs, particularly those that are process-oriented.

So yes, I am modifying the server's resource state, though not in the ubiquitous object-passing way.

That's kind of the general idea. Let me know if you want to know more :)

[...]

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

Yes, I think so, actually, the more I think about it the more I think that supportedAction/supportedOperation looks like it's analogous to supportedProperty, when, in fact, they are talking about two different things. SupportedOperation is talking about HTTP operations the server supports, whereas supportedProperty is talking about properties acceptable for the rdf:Class. I think it would be wise to disambiguate the two, though I don't have a definitive idea of the best way to do that until we nail down Hydra's "centricity". Assuming that Hydra is more client centric, the possibilities that come to mind are:

1. Change supportedAction
2. Change supportedProperty
3. Drop the supported prefix for both words so that we have hydra:Property and hydra:Action. Then a hydra:Class would have "properties" and "actions", avoiding the whole "supported" ambiguity altogether.

This may be better handled as a separate Github issue. Thoughts?

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

Nice.

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

I agree.

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

Yes :-D

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

Having a hypermedia-driven read-write API built on linked data (especially JSON-LD) is a high priority for us right now. We're happy helping out with whatever you need help with, though we see our greatest abilities right now as helping out with the spec and building a showcase using Scala on the server with a JavaScript client, using a simple domain from schema.org. We could do a simple blog engine or event management system, whichever you think is best. 

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

[1]: http://lists.w3.org/Archives/Public/www-tag/2002Jul/0090.html
[2]: http://lists.w3.org/Archives/Public/www-tag/2002Jul/0128.html

Received on Friday, 23 May 2014 16:40:45 UTC