RE: Hydra and the uniform interface

On Thursday, December 12, 2013 5:12 AM, Ryan J. McDonough wrote:
> I’ve been trying to parse this thread for the past few hours and I
> think I understand what Mark is getting at, and wanted to add my 2¢
> to see if it helps any. 

Thank you very much for taking the time to do so Ryan. Much appreciated.


> On Dec 11, 2013, at 5:37 PM, Markus Lanthaler wrote:
>> On Friday, December 06, 2013 9:59 PM, Mark Baker wrote:
>> 
>> On Thu, Dec 5, 2013 at 3:38 PM, Markus Lanthaler wrote:
>> 
>>>> 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.
>>> 
>>> I understand the objective, as I shared it when I developed RDF Forms
>>> over 10 years ago. It too was type based like Hydra (something I've
>>> mentioned I wouldn't do again). But it made no attempt to change the
>>> HTTP contract, because it didn't need to.
>> 
>> I'm trying to understand why you think Hydra changes the HTTP contract
>> but I'm afraid I still can't follow you. 
> 
> I think what Mark has been trying to point out is Hydra, in it’s current
> form, suggests some level of coupling. Using an example from earlier:
> 
> {
>     "@context": ...,
>     "@id": "#order",
>     "@type": "Link",
>     "supportedOperations": [
>         {
>             "@type": [
>                 "schema:OrderAction",
>                 "Operation"
>             ],
>             "method": "POST",
>             "expects": "schema:Product",
>             "returns": "#Order"
>         }
>     ]
> }
> 
>
> HTTP says that a successful POST operation could return a 200 or 201
> response code that may include a response body. In this case, Hydra is
> building on the HTTP response codes but also asserting that for this
> particular URI, it’s also always going to return an #Order instance in the
> response body.

Hmm.. no, not exactly. The spec says

    Optionally, it is also possible to describe what information the
    server expects or returns, including additional information about HTTP
    status codes that might be returned. This helps a developer to
    understand what to expect when invoking an operation. This information
    has, however, not to be considered as being complete; *it is merely a
    hint*. Developers should, e.g., expect that other HTTP status codes
    might be returned and program their clients accordingly.

and the definition of returns says

    hydra:returns
    The information returned by the Web API on success

So it is really just a hint. Probably this has to be clarified or
highlighted somehow in the spec. I've raised ISSUE-21 to track this.


> What I believe Mark is getting at is that the client can’t
> reliably assume that a 200 (Ok) response could would always return an
> #Order instance. At any time, the sever must be free to change the flow
> and return an #Invoice instance instead.

Fully agreed.


> Browsers work well because they
> only know that the next link or form post will return “something."
> Browsers don’t even assume that they’ll get back HTML either.

No, but humans controlling them have expectations about what they get back
when they follow a link or fill out a form. If you break those too often,
the user will give up and use a different site instead. In other words, you
site's usability sucks in that case.


> The browser
> knows what media types it can understand and determines if it can render
> it by looking at the content-type header. If it can't display it, it asks
> the user what to do with it. Each link does not scribe what’s on the other
> end of the link, or what it might look like, its just a link.

It does, otherwise the user wouldn't be able to select the right link to
follow. It is just that machines can't understand the labels or images used
to convey that information.


> This detail also invites itself to germinated client bindings that would
> ultimately couple clients to specify server implementations.

Yeah, that's one of the things I'm most concerned with. I tried to address
that by not including any URLs in a Hydra API description which allow to do
that in a practical manner. If you need to find out the URLs at runtime
anyway, it's that much more work to process the API description at the same
time.


> WADL sets up
> a nice environment for describing an XML IDL that can be used to generate
> clients from. One of the things that a WADL Document would describe is
> both what a given URI would return in a successful response as well as the
> types of errors that the client could get.

Right, in WADL the coupling is, as in most current API libraries (and
documentations for that matter), on the URL structure.


> The generated clients only know
> how to deal the error defined in the WADL document. In reality, a client
> really ought to be able to handle all of the HTTP error code and redirect
> codes. It’s the client that needs to handle the errors. It’s not the
> servers job to define every error for every condition. The server needs to
> be free to make changes as then need too.

Again, fully agreed. I probably did a bad job explaining that in the spec.


> Mark, is this kind of where you were going?

Of course I'd like to know that as well :-)


Thanks a lot again Ryan for trying to help here. At least we've found
something that has to be made much clearer in the spec. I remember you were
working on a little prototype. How is that going?


Cheers,
Markus


--
Markus Lanthaler
@markuslanthaler

Received on Friday, 13 December 2013 15:15:51 UTC