

Haters Gonna HATEOAS - steveklabnik
http://timeless.judofyr.net/haters-gonna-hateoas

======
qntm
I'm not sure I fully understand the benefits of this final HATEOAS step in the
implementation of a RESTful interface.

The idea seems to be to add XML to the usual output from a resource endpoint,
which will tell you what operations are available at that endpoint. My
question is whom "you" refers to.

If we're enabling a human being to explore the API manually while creating an
client for the API, then I have no problem with that. We've made the API self-
documenting to an extent and that's good. But there's no substitute for actual
documentation, of course. And an API is not its documentation. Functionally,
it's the same interface, but with "comments" of a sort.

If we're enabling a client to follow those links then what we're actually
doing is forcing the client to make two requests on every operation: one to
look up which URI to use, and then another to make the actual request. Also,
the client has to be smart enough to figure out which URI it wants to use for
the actual request, which takes extra work for the client developer (gotta
parse that XML for the <link> with rel="/linkrels/entry/newcomment"). And,
ideally, smart enough to expose any new <link>s which have become available.
And of course, while you can change the API a little under the covers (the
"uri") you still can't change your "rel" schema, because that's the part that
the client is dependent upon.

Am I missing something?

~~~
steveklabnik
The idea is that a computer could navigate your API as easily as a human
could. You're encoding the interface of the state transitions into your
responses.

> one to look up which URI to use, and then another to make the actual
> request.

The idea is that they'd naturally flow. Think about it: if I'm going to
comment on a blog post, I've already visited it, and the link is already
there.

> gotta parse that XML for the <link>

You'd already be parsing the entire document anyway, this is essentially free.

Maybe try checking this out: how to GET a cup of coffee:
<http://www.infoq.com/articles/webber-rest-workflow>

------
steveklabnik
There's some parts of this that I'd like to elaborate on in the future, but I
think this is a good starting place. Any REST masters want to share some
thoughts? I'm still learning all of this stuff, too.

