Re: Hydra and the uniform interface

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. 


On Dec 11, 2013, at 5:37 PM, Markus Lanthaler <markus.lanthaler@gmx.net> wrote:

> Hi Mark,
> 
> Sorry for the delay
> 
> 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. 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. 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. 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. 

This detail also invites itself to germinated client bindings that would ultimately couple clients to specify server implementations. 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. 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.

Mark, is this kind of where you were going?


> 
> 
> [...]
>>> 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.
>> 
>> tldr; no, we don't agree.
>> 
>> That's a complicated example though. On one hand, AtomPub and WebDAV
>> are competitive and incompatible in significant ways. But on the other
>> hand, the point of substitution is not to ensure implementation
>> consistency - in this case, that clients would be able to interop
>> perfectly with each server implementation - but exactly the opposite,
>> to modify system functionality by using new and/or different
>> components in a layered architecture. For example, by sticking a cache
>> in front of a Web server; same contract, different overall behaviour.
> 
> OK, then at least we've found an example worth a closer look. Why do you
> think that AtomPub and WebDAV don't change the HTTP contract but Hydra does?
> 
> 
> [...]
>> I'm still not entirely sure what points we disagree upon. We've got
>> that one above, for sure, but I'm not sure what might be gained from
>> deep diving on it. I suspect there's also disagreement about the
>> generic meaning of responses (as previously mentioned) and probably
>> the roles of predicates, types, and their relationship to the uniform
>> interface. But I don't know. Perhaps I could motivate that
>> conversation with a suggested edit to the spec (in case it wasn't
>> clear already what I would like :), so here goes ...
>> 
>> Remove everything including and after "While links are enough to build
>> read-only Web APIs" in sec 4.1.
> 
> Wow. I didn't expect something like this. So you are saying that all that's
> missing is a concept to define a link, i.e., hydra:Link? How would an
> application know how to use such a link? Without any further information,
> the only solution I see is to hardcode it into a client.
> 
> 
>> But perhaps that will just bring up the same issues we're already
>> discussing. If so, I'm not sure that there's anything more I can add
>> to this conversation, so if I haven't convinced you yet, I probably
>> won't be able to. Perhaps somebody else would like to take that up
>> (Stu?)
> 
> Well, I'm still trying to understand you. I'm not trying to convince you
> with my statements/question but find out what you are trying to say to I
> don't seem to understand. Given your experience I'm of course very
> interested in your thoughts. It's just that I still struggle understanding
> them. Thanks for taking the time to respond to my mails. Much appreciated.
> 
> 
> Cheers,
> Markus
> 
> 
> --
> Markus Lanthaler
> @markuslanthaler
> 
> 

Ryan-
——————————————————————
http://damnhandy.com
@damnhandy