In REST is HATEOAS really about self-discovery or about navigation?

Question

I'm trying to learn about REST and having problems with the concept of HATEOAS (Hypermedia As The Engine Of Application State). What is it for?

It seems to me the majority of commenters on the web think that HATEOAS should be used by a client to discover how to use a RESTful web service. And most seem to conclude that HATEOAS is not worth including in RESTful web services for one of two reasons:

1) HATEOAS only gives URLs but these are useless by themselves without knowing what methods can be used with each URL (eg HTTP GET, POST, PUT). Since the additional information must be passed to the client out of band (eg via documentation) then there is no point in using HATEOAS;

2) Similar to (1) but takes it a step further: The client can figure out what methods are applicable to a given URL by calling the HTTP OPTIONS method. However, the client still needs out of band information, to describe the format of the data it must pass for, say, POST or PUT methods. So we end up in the same place as (1) - HATEOAS isn't sufficient for a client to discover everything it needs to know, so why bother with it.

These arguments seem valid if HATEOAS is supposed to be used by a client to discover how to use a RESTful web service. However, is that what HATEOAS is for? From the few examples I've seen, it seems to me to be perfect for navigating through a web service - I've performed a certain action, now what are the valid actions I can perform next? That seems to me to gel with the "Application State" part of HATEOAS but very few articles I've read talk of it in terms of navigation, almost all are about discovery.

So, is HATEOAS about discovering how to use a RESTful web service or is it really about navigation?

Answer 1

Disclaimer: answer offered without first rereading the Fielding thesis.

HATEOAS supports the discovery of previously unknown application states.

Think state machine. The hypermedia representation sent to the application describes a current application state, and it describes which triggers are valid transitions out of the state.

It doesn't necessarily describe how to implement the trigger.

As usual, consider the web as the Ur example. You start your Wikipedia application by directing your browser to the landing page, and three hours later you find yourself reading about Citrus Taxonomy.

How does that happen? Wikipedia sends a hypermedia description (text/html) of the application state (the landing page); included in the hypermedia are links (anchor tags). The application (browser) knows what to do with those because the implementation was written with awareness of the html specification.

When we write html that conforms to a new version of the specification, the hypermedia doesn't tell old browsers how to implement it -- Netscape 2.0 doesn't magically "discover" how to implement html5 embedded video.

In general, the hypermedia document provides the triggers that are supported, but the client is expected to ignore any triggers that it doesn't recognize. Definitions of the triggers themselves are out of band.

So, is HATEOAS about discovering how to use a RESTful web service or is it really about navigation?

Consider a "Choose Your Own Adventure" book.

To visit the Cave of Wonders, turn to page 17.

Is the book telling you how to navigate the pages, or is it telling you how to discover the story?

Answer 2

@VoiceOfUnreason's answer suggests that HATEOAS is really just about links. However, the Programmers StackExchange question @RobertHarvey linked to, What does HATEOAS offer for discoverability and decoupling besides ability to change your URL structure more or less freely?, suggests it's more complicated than that, and HATEOAS includes both using the OPTIONS method to determine which methods can be called on a resource, and defining a media type to specify the format of data in the request and the response.

One of the answers to that question ("What does HATEOAS offer...") includes a link to a blog post from Roy Fielding, who originally defined REST: REST APIs must be hypertext-driven. Some snippets from that blog post:

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.]

A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC’s functional coupling].

A REST API should never have “typed” resources that are significant to the client. Specification authors may use resource types for describing server implementation behind the interface, but those types must be irrelevant and invisible to the client. The only types that are significant to a client are the current representation’s media type and standardized relation names. [ditto]

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.]

(As an aside: I get the impression from many blog posts that a lot of people see HATEOAS as sort of an optional extra to REST. However, Roy Fielding's comments quoted above indicate HATEOAS is actually central to REST and you can't have a RESTful API without it.)

If anyone finds this answer useful please upvote @RobertHarvey's comment to my question above, the one that has the "What does HATEOAS offer..." link.