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 us

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?