RE: Hydra and the uniform interface

On Tuesday, November 26, 2013 7:12 PM, wrote:
> Marcus,
> 
> Creating a new thread. Ruben and I have covered related ground before
> in LDP where we also disagreed, but since this actually stands a
> chance at being useful ;), it's important we're in synch.

I've follow the development of LDP but I can't remember your discussion with
Ruben, so thanks for bringing it up again here.


> On Tue, Nov 26, 2013 at 7:32 AM, Markus Lanthaler
> <markus.lanthaler@gmx.net> wrote:
> > On Sunday, November 24, 2013 5:10 PM, Mark Baker wrote:
> >> Sure, but that's not part of the interface to the service so out of
> >> scope IMO. The method is POST which defines the contract between
> >> client and server. Though the server may only implement one of those
> >> things above, that's an implementation detail that the more generic
> >> POST interface hides from the client.
> >
> > I think I have to disagree with this. Hydra's operations specify the
> > semantics of an HTTP operation at a higher level of abstraction.
> > HTTP's methods are enough to implement things like proxies, caches
> > etc. but they are IMO not enough (by themselves) to convey the
> > semantics of an operation in terms of business logic.
> 
> See below about sufficiency... But I will disagree with you that
> Hydra's operation are higher-level; they are at the same level as HTTP
> methods. Consider, when a server publishes an endpoint:
> 
> <> :POST <http://example.org/my-endpoint> .
> 
> it is declaring that it accepts POST requests to that URL, and that is
> the entire contract.

Really? What would you post to that URL? An image? A textfile? A JSON-LD
file? What would the consequences be of doing so?


> If it wants to create things (as opposed to
> annotate things, or "extending a database"), that is its prerogative
> as an implementation and it needn't indicate that to the client a
> priori (201 is after the fact, of course),

You are right, it doesn't *have to*. But, let's assume we have this

  <> :POST <http://example.org/resource-A> .
  <> :POST <http://example.org/resource-B> .

How would a client know which URL it should POST to? On the human web these
things work because the semantics are explained in natural language (or
perhaps icons). Machines don't understand that. That's why we need to give
them more machine-readable information. Hydra's operations are a simplistic
model to do so. There have been numerous efforts in the past to describe
this in much more detail but I think they are all way to complex to be
practical (at least for the time being).


> nor require the client
> indicate which one it wants/expects (as that would be tunnelling ala
> SOAP).

Agreed. A client select between a number of server-offered choices.


> The reason that matters from a REST POV is because REST
> requires that components be able to be substituted behind a common
> connector, and obviously that couldn't happen if clients were coupled
> to any aspect of the component/implementation.

Right, but what has that to do with Hydra operations?

 
> > POST, e.g., is specified to be non-safe and non-idempotent. That doesn't
> > tell you the difference between just storing an (opaque) order
> > representation on a server acting purely as a file server e.g. vs.
> > ordering goods. Caches etc. do not care about such details - they
> > don't have to. But clients need to IMO.
> 
> They don't. And if they do, as above, they're not RESTful because
> they're not using the uniform interface.

Sorry, I don't understand how you can claim that at all. Let's use a typical
e-commerce API as an example. How can you implement it in, let's say, Turtle
without requiring the client to understand what the predicates stand for? I
would like to be proven wrong but I can't imagine you can build one by using
just things like

  <> :POST <http://example.org/cart/> .


> All clients need to know is which links they should be interested in
> and how to interact with them.

And how do they know that? Maybe we are just talking past each other or the
spec isn't clear enough in explaining what operations are. They are
effectively the same as link relations:

  vocab:order rdf:type hydra:Link ;
         hydra:supportedOperations [
             rdf:type schema:OrderAction, hydra:Operation ;
             hydra:method "POST ;
             hydra:expects schema:Product ;
             hydra:returns vocab:Order ;
         ] .

or in JSON-LD

{
  "@context": ...,
  "@id": "#order",
  "@type": "Link",
  "supportedOperations": [
    {
      "@type": [ "schema:OrderAction", "Operation" ],
      "method": "POST",
      "expects": "schema:Product",
      "returns": "#Order"
    }
  ]
}

This tells a client that when it encounter a triple like

  <> :order </order> .

It can POST a schema:Product to /order to order it.


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

Well, that's basically the same. You move the semantics into link relations.
Operations decouple the "functional semantics" from link relations so that
you can use them to describe link relations or operations allowed on
resources (or resource classes) themselves.

I believe we agree already and that it's just the terminology which causes
some confusion. But maybe I'm also wrong and you have something else in
mind. If so, I think the easiest way forward is to explain it based on a
concrete example.


Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Wednesday, 27 November 2013 12:57:37 UTC