Why document RESTful APIs if they are supposed to use HATEOAS?

Question

In an effort to grasp the underlying purpose of a RESTful API, I've begun delving into HATEOAS.

According to that wikipedia page,

A REST client needs no prior knowledge about how to interact with any particular application or server beyond a generic understanding of hypermedia. By contrast, in a service-oriented architecture (SOA), clients and servers interact through a fixed interface shared through documentation or an interface description language (IDL).

Now, I don't really understand how that's supposed to work, unless there exists prior knowledge of what is available in an API, which decries the stated purpose of HATEOAS. In fact, tools such as Swagger exist for the express purpose of documenting RESTful APIs.

So while I understand that HATEOAS can allow a webservice to indicate the state of a resource, I am missing the link (haha) demonstrating how a client application could possibly figure out what to do with the returned follow-up links in the absence of some sort of "fixed interface".

How is HATEOAS supposed to accomplish this?

Answer 1

You're confusing things. Tools like Swagger don't exist for the express purpose of documenting RESTful APIs. They exist for the express purpose of documenting HTTP APIs that aren't RESTful! You need tools like that for APIs that are not hypertext driven and focus documentation on URI semantics and methods instead of media-types. All those fancy tools that generate lists of URIs and HTTP methods are exactly the opposite of what you are supposed to do in REST. To quote Roy Fielding on this matter:

A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

HATEOAS doesn't preclude the need for all documentation. HATEOAS allows you to focus your documentation on your media-types. Your application is supposed to conform to the underlying protocol -- HTTP, most of the time -- and the authoritative documentation on that protocol is all your clients should need for driving the interaction. But they still need to know what they are interacting with.

For instance, when you enter Stack Overflow, you know there are users, questions and answers. You need documentation on what exactly are those things, but you don't need documentation detailing what a click on a link or a button does. Your browser already knows how to drive that, and that's how it works everywhere else.

To quote another answer, REST is the architectural style of the web itself. When you enter Stack Overflow, you know what an User, a Question and an Answer are, you know the media types, and the website provides you with the links to them. A REST API has to do the same. If we designed the web the way people think REST should be done, instead of having a home page with links to Questions and Answers, we'd have a static documentation explaining that in order to view a question, you have to take the URI stackoverflow.com/questions/, replace id with the Question.id and paste that on your browser. That's nonsense, but that's what many people think REST is.