Re: Hydra and the uniform interface

On Wed, Nov 27, 2013 at 7:57 AM, Markus Lanthaler
<markus.lanthaler@gmx.net> wrote:
>> <> :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?

In that example, all of the above (and everything else). But sure, the
contract could be extended to say,

<> rdfforms:acceptedMediaType "application/json+ld" .

> What would the consequences be of doing so?

>From a contractual POV, all the client knows is that it POSTed the
data, and the server returned a 200 indicating it successfully did
whatever it wanted with the data. The client has zero visibility into
the state of the server/resource.

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

...

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

See below

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

Right, that's consistent with my view (AFAICT) and exactly how I'd
declare an order path. But the HTTP 200 response that results from
that potential interaction being followed still just means "The POST
succeeded" and so is not an "operation" in the sense that most people
understand. If the 200 meant "the product was ordered" - which I
believe is what you think is necessary and support with Hydra
operations - then you couldn't do the implementation-substitution
manoeuvre we talked about before because the other implementation's
200 responses will mean the former, not the latter.

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

Nothing was moved. We have transformed the architecture of the solution.

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

I hope we agree, but don't think we do. I'm not 100% sure that we
disagree on that point above though. Hopefully so, but if not, I'm at
a loss to explain why you'd ask "Do you really think POST/PUT etc. are
enough?"

Received on Thursday, 5 December 2013 17:07:31 UTC