RE: Hydra and the uniform interface

On Wednesday, November 27, 2013 12:48 AM, Stuart Charlton wrote:
> On Nov 26, 2013, at 11:11 AM, Mark Baker wrote:
> >> Do you really think POST/PUT etc. are enough? Or do you shove those
> >> semantics in to the media type? They need to be somewhere...
> >> currently they are documented in prose out of band.
> >
> > I feel that the uniform interface is  sufficient, yes (though that
> > doesn't mean that the currently standardized set of HTTP methods are
> > sufficient). And nothing need be shoved in to the media type for this
> > to occur except for the usual links and predicates/relations.
> 
> This I think is the key.
> 
> An operation outside of POST is, at best, a _programmatic label_ or
> alias for a particular state transfer's advertised semantics.
> However, the surrounding predicates/relations (or human prose) are what
> describe what it does.

Right. A "Click here" button without any context is just as useful as a the
knowledge that you can POST to a URL. You can click anywhere just as you can
POST to any URL. The question is what consequences the client/user can
expect in response to his action (clicking, POSTing).


> Put in programmatic terms, we're used to symbolic linking against
> method/function symbols, when I think a more natural approach to
> describing state transfer is with a Design-by-Contract approach, where
> the operation symbol matters less than the pre-conditions, post-
> conditions, and invariants that surround it to describe the affordance
> of the POST link in the representation.   Those might all be described
> in human prose in a link predicate specification or they might be
> described in media (like a JSON-LD document with JavaScript
> expressions, for example).

Hydra's operations and schema.org's actions are a simplistic approach to
describe these pre- and post-conditions. At the moment they are nothing more
than a unique identifier. There have been many efforts in the past to
describe this in much more detail, Ruben's RESTdesc is an approach which
solves this very elegantly.

Hydra takes a shortcut to reduce the complexity by several orders of
magnitudes (IMO, anyway). Instead of trying to start with a framework to
describe pre- and post-conditions, it starts with a framework which gives
them a name but doesn't describe them any further. Thus we have e.g. a
CreateResourceOperation.

I'm not saying it wouldn't make sense to describe CreateResourceOperation
more explicitly in terms of, e.g., pre- and post-conditions. I'm convinced
it would. But we are not there yet... and it might take quite some time till
we get there. In the meantime we can emulate it with something much simpler.
As soon as we get there, we can start to describe these simple "Operations"
in much more detail in a machine-processable way. The advantage is that we
don't have to wait for that to happen. In a sense, we try to avoid the
classical chicken-and-egg problem.


> Consider the latter case, where we could describe conditions in media.
> The hyperlinked transitive closure of these representations together
> would describe a protocol state transition system that's independent
> from any specific implementation.   A programmatic user agent then uses
> this information to perform action selection towards its goal(s) and/or
> preferences.     Unfortunately that's all easier said than done, as
> action selection is an active topic of  automated planning literature
> (many practical approaches exist, thankfully).

That's a goal, yes. It's also the reason why operations are completely
decoupled from the rest. They don't define the HTTP method e.g. They also
don't define the predicates. It's the other way round. HTTP operations are
described in terms of the operations they afford.


> So IMO the Hydra team will have to make a determination of how far it
> wants to go in terms of describing the semantics of POST-method based
> affordances.

Why do you think we need to decide this now? Do you think there's something
in the current model that prevents it advance from

> [...] a Web hypermedia documentation vocabulary (i.e. tie together link
> relations, data types, etc. into a structure that can be parsed and
> rendered in HTML for a human to manipulate)? [...]   

to

> [...] a vocabulary for Hypermedia designers to express
> affordances for a protocol state transition system, where the machine
> agent itself does the processing of how to select the right sequence of
> actions towards a goal?

I hope the explanation above made it clear that that's a goal. But we will
need to address it step-by-step otherwise it risks getting too complex too
early which will be very harmful to adoption.


> This is what Hydra-the-goal looks like though
> it doesn't quite match Hydra-as-specified.

Sure, a client will have to know the operations it likes to invoke and those
have to be used in the Hydra description of the API it is accessing but then
there's nothing that prevents a client to find its way through the API to
achieve a certain goal. Even if you just take the operation's class
hierarchies or other, similar relationships into account, it already allows
you to build quite adaptable clients. There's certainly much more to do in
that direction but we need to start somewhere.


> I apologize if these questions have already been answered, as I have
> been in lurk mode.

Those are very good questions and I hope my answers clarify them a bit. I
would love to hear why you think Hydra has to decide between being a
"hypermedia documentation vocabulary" and a "vocabulary to express
affordances". Isn't the difference just in how it is used?


--
Markus Lanthaler
@markuslanthaler

Received on Wednesday, 27 November 2013 13:52:31 UTC