RE: Hydra and the uniform interface

On Thursday, December 05, 2013 6:07 PM, Mark Baker wrote:
> On Wed, Nov 27, 2013 at 7:57 AM, Markus Lanthaler 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" .

Right. That works well for specific media types but not so much for very
generic ones such as XML, JSON, and JSON-LD I think. I think you need some
more information to do anything useful. The information here is basically
equivalent to

  <form action="" method="POST" enctype="application/json+ld">
  </form>

(if it would support that media type). I still struggle to see how you could
build anything useful with just that information.


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

Right


[...]

> > {
> >   "@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.

And if the new implementation would advertise the same Hydra API
documentation? If I understand you correctly, you say that HTTP doesn't
define any contract apart "200 POST succeeded". I think it's possible to add
more semantics on top of this HTTP contract.

You can either define them in a media type specification and expose them by
typing the requests/responses with that media type, as e.g. AtomPub does, or
use some other mechanism. Hydra is an attempt to make these contracts
machine-readable and discoverable at runtime.

If two implementations advertise the same contract, they can be substituted.
If not, they can't. The same applies to an AtomPub server and a WebDAV
server IMO. Both speak HTTP and adhere to the contract defined by HTTP but
they also extend it (or specialize it if you want). I think we agree that
you can't substitute an AtomPub server with a WebDAV one.



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

And how is that any different?


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

Could you POST a simple descriptive example illustrating the points you
think we disagree on?


--
Markus Lanthaler
@markuslanthaler

Received on Thursday, 5 December 2013 20:39:24 UTC