REST and HATEOS definitions self-violating? - rest

Question

QUESTION: Can HATEOAS in REST be considered a valid proposition when it is self-evidently internally contradictory : If an interface is said to not be RESTful (according to Fielding), when a Client cannot utilize the in-band data (URI's) from the Response Hypertext (Hypermedia) without reference to an external (out-of-band) document, and therefore tightly coupling Client and Server according to Fielding, how can we do anything but fail Roy Fielding's prima facie assertion?
It seems to me that Fielding's exposition makes HATEOAS and REST an internally contradictory proposition that cannot be fulfilled with the current technology - unless someone knows how to it without referring to out-of-band data?
(EDIT) I suspect no-one is reading/has read Fielding's rant, so here's the most relevant piece:
"A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]"
We all keep asserting that we must have out-of-band knowledge of the URI's available methods beyond the initial data stream. Note how Fielding very stridently tells us that this is failure. Yet, it's how we're all dong it, me included. But Fielding screams No back at us.
(EDIT: because no-one's reading ithe explanation).

Answer 1

There are three pieces of prior knowledge that REST allows: the home page of the API (in browsers, this is supplied by the user typing into the address bar); an understanding of common media types, such as HTML (provided by browser developers); and link relations that inform a client application can look at when deciding what to do (e.g. rel=stylesheet links get automatically downloaded and parsed by graphical browsers to make the documents they render look pretty).
What REST prohibits is a client knowing it can do things like read an ID from a certain place on your webpage and then append it onto the end of youtube.com/watch?v= to get to a YouTube video. In stead, you should define a "video-clip" link relation and use your media type's hyperlinking mechanism to provide the full URL, not just the ID.

Answer 2

So, the answer to my question seems to be that none us know how to do it the way Fielding said it should be done, so none us know how to acheive a HATEOAS compliant RESTful API without violating Fielding's primary assertion regarding out-of-band data, and therefore making our app non-RESTful in so doing.
Everyone stridently believes they have this answer right, but we're all ignoring the fact that Roy Fielding says we are all wrong. He says we're all writing RPC's.
Roy Fielding: REST APIs must be hypertext-driven
"I am getting frustrated by the number of people calling any HTTP-based interface a REST API"
It boils down to the fact that we are not building the kind of apps that lend themselves to Roy's thesis on REST. Indeed, he believes the proposition that we would render our URI's as part of CDATA that includes the "method" or that the context of the URI would self-evidently provide it, like the FORM element does. He explicitly rails against the OpenSocialst REST API stating that it is not RESTful.
Here: “anchor elements with an href attribute create a hypertext link that, when selected, invokes a retrieval request (GET) on the URI corresponding to the CDATA-encoded href attribute.” Identifiers, methods, and media types are orthogonal concerns — methods are not given meaning by the media type. Instead, the media type tells the client either what method to use (e.g., anchor implies GET) or how to determine the method to use (e.g., form element says to look in method attribute). The client should already know what the methods mean (they are universal) and how to dereference a URI.
I tend to design JSON responses that provide this approach:
GET /account/12345 HTTP/1.1
{
"account": {
"number": "12345",
"currency": "usd",
"balance": "100.00",
"deposit": {
"href": "/account/12345/deposit",
"action": "POST"
},
"withdraw": {
"href": "/account/12345/withdraw",
"action": "POST"
},
"transfer": {
"href": "/account/12345/transfer",
"action": "POST"
},
"close": {
"href": "/account/12345/close",
"action": "DELETE"
}
}
}
... adding additional properties to the design as needed, but these are the basics.
I believe this allow the Client to be written to be RESTful, but in so doing I am using the Response Body, which Fielding says is not what he intended.

Answer 3

No, REST and HATEOAS do not contradict each other. In fact the proposition doesn't even make sense because HATEOAS is part of the definition of REST. They aren't two separate things.
To better understand what Fielding means by out-of-band knowledge I suggest thinking about a web browser. A web browser is a generic client that implements a set of standards (HTTP, HTML, URI, etc). Any of the standards that the client implements can be thought of as in-band. Anything that is not expressed in one of the standards implemented by the generic client is out-of-band.
If you have a resource that looks like this
GET /some/resource HTTP/1.1
Content-Type: application/json
{
"author": "/authors/me",
"foo": 42
}
As a human, I can look at this and recognize that the value of "author" looks like a link and I can try to follow it, but a generic browser only recognizes it as plain JSON. It's just a string. Interpreting that "author" is a link requires out-of-band knowledge.
The solution is to choose a hypermedia media type that defines how to express a link. Here's that example expressed in HAL.
GET /some/resource HTTP/1.1
Content-Type: application/hal+json
{
"_links": {
"author": { "href": "/authors/me" }
},
"foo": 42
}
A generic client can be developed that understands HAL. My API and your API can both use the same client without knowing anything about each other or the client knowing about either API.
The question about how to know which method to use with a link is also up to the hypermedia media type to define. HTML does it by defining constructs whose semantics imply a method. The anchor tag foo implies a GET request. The form tag has similar well defined semantics. A JSON based hypermedia format will have to define it's own structures and semantics for those structures. All of this is considered in-band because it's part of a standard that can be implemented by a generic browser.
So, if you want to get the Roy Fielding stamp of approval for your REST API, you need to be using a standardized generic hypermedia media type that is capable of describing everything your application needs to do. My favorite is JSON Hyper-Schema. It's the best at describing something like a form post without out-of-band knowledge because it uses a JSON Schema to describe what data the server expects.