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?

Convert

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.

Manasseh

My confusion, then, stems from the fact Swagger states, "Swagger is a simple yet powerful representation of your RESTful API." Are they just mistaken, then? – Convert

I wouldn't say mistaken. REST has became a buzzword for any HTTP APIs, and if you are advertising a product, to say it's targeted at RESTful APIs is a good marketing strategy, even if you know that people who actually design real RESTful APIs won't need your product. It adds to the confusion, but at this point it can't get much worse. In fact, some people gave up on the REST term, since it's impossible to reverse the buzz now, and refer to real RESTful APIs as Hypermedia APIs. – Manasseh

I'd vote for saying swagger folks are just mistaken. Maybe rest level 2 in richardson maturity model. – Panto

@PedroWerneck I couldn't agree more! I'll quote this summary on occasion :) – Catharine

@ChrisDaMour I have yet to understand why sooo many people mention the Richardson maturity model in combination with REST. In my opinion this is utterly garbage. First, there is no REST below level 3 to start with and second, even at level 3 there is no guarantee that the API is actually following the REST ideas. REST is a model to decouple clients from servers in a distributed system and doing only half the work doesn't achive this. In my sense this is an all or nothing approach which comes at high initial overhead costs but with low maintenance overhead once implemented. – Glaive

@RomanVottner yeah i'm with you, but it is a good in that it lets people who don't get it see where they are at on some scale, and hopefully opens up doors to what they are missing. I spent some time talking about why the maturity model can be useful at youtu.be/u_pZBBELeEQ?t=462 i talk specifically only lvl 3 being restful, and how REST API has been horribly bastardized – Panto

Answer 2

There are various answers to this question depending on the level of autonomy of the client interacting with the service ...

Lets first look at a human driven client - the browser. The browser knows nothing about banks, concerts, cats and whatever else you find on the net - but it certainly knows how to render HTML. HTML is a media type with support for hypermedia (links and forms). In this case you have a perfectly working application with a client that only understands generic hypermedia. The "fixed interface" here is HTML.

Then we have the autonomous clients or "scripted" clients that are supposed to interact with a service without human interaction. This is probably the kind of client you are thinking of when comparing REST to SOA(P). You could find such clients in integration scenarios where two independent computer system exchange data in some predefined way.

Such autonomous clients must certainly agree on something in order to interact with each other. The question is what this "something" is or is not.

In a service oriented architecture the clients agree on specific URLs/endpoints and specific "methods" to invoke on those endpoints (RPC) - this adds coupling on the URL structure used. It also forces the client to know which method to call on what service - the server cannot change URLs and it cannot move a "method" from one service to another without breaking clients.

REST/hypermedia based systems behaves differently. In such a system the client and server agrees on one common entry URL where the client can lookup (GET) a service document, at runtime, describing all the possible interactions with the server using hypermedia controls such as links or forms. These hypermedia controls informs the client about how to interact with the service (the HTTP method and payload encoding) and where to interact with the service. Which in essence means we do not have "a service" anymore but possibly many different services as the client will be told, at runtime, where and how to interact with them.

So how does the client know which hypermedia controls it should look for? It does so by agreeing on a set of identifiers the server will use to identify the relevant controls. For links this is often referred to as "link relation types".

This leads us to what kind of "something" it is that servers and clients agree on - it is 1) a hypermedia enabled media type, 2) the root service index URL, 3) the hypermedia control identifiers and 4) the payload expected for each of the controls. At runtime the client then discovers the remaining URLs, HTTP methods and payload encoding (such as JSON, XML or URL-encoded key/value pairs).

Currently there are a small set of general purpose media types for hypermedia APIs - Mason, HAL, Sirene, Collection JSON, Hydra for JSON-LD and probably a few more.

If your are interested then I have covered this topic in various blog postings:

• The role of media types in RESTful web services
• Media types for APIs
• Selling the benefits of hypermedia in APIs
• Hypermedia API documentation example
• RESTful resources are not typed

Perice

I really appreciate this explanation- it explains the purpose of HATEOAS nicely, I think. – Convert