Hydra and the uniform interface

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.

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:
>> On Fri, Nov 22, 2013 at 5:01 AM, Ruben Verborgh wrote:
>> > Alternatively, we could learn from
>> > http://tools.ietf.org/html/rfc2616#section-9.5 to define
>> > standard operations:
>> >
>> >> POST is designed
>> >>    to allow a uniform method to cover the following functions:
>> >>
>> >>       - Annotation of existing resources;
>> >>
>> >>       - Posting a message to a bulletin board, newsgroup, mailing list,
>> >>         or similar group of articles;
>> >>
>> >>       - Providing a block of data, such as the result of submitting
>> a
>> >>         form, to a data-handling process;
>> >>
>> >>       - Extending a database through an append operation.
>> >
>> > CreateResourceOperation covers the second thing here.
>>
>> 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. 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), nor require the client
indicate which one it wants/expects (as that would be tunnelling ala
SOAP). 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.

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

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

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

Received on Tuesday, 26 November 2013 18:12:11 UTC