3

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?

marked as duplicate by Bart van Ingen Schenau, Community Jan 17 '16 at 0:52

This question has been asked before and already has an answer. If those answers do not fully address your question, please ask a new question.

  • 1) "According to the Richardson Maturity Model, HATEOAS is considered the final level of REST. This means that each link is presumed to implement the standard REST verbs of GET, POST, PUT, and DELETE (or a subset). Thus providing the links as shown above gives the client [all] the information they need to navigate the service." -- spring.io/understanding/HATEOAS – Robert Harvey Jan 15 '16 at 6:37
  • 2) "A client does not need to understand every media type and communication mechanism offered by the server. The ability to understand new media types can be acquired at run-time through "code-on-demand" provided to the client by the server." -- en.wikipedia.org/wiki/HATEOAS, which also provides detailed examples of HATEOAS in action. – Robert Harvey Jan 15 '16 at 6:41
  • 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 -- Isn't learning how to navigate through a web service part of the discovery process? – Robert Harvey Jan 15 '16 at 6:44
  • 4
  • 1
    @RobertHarvey: I found the spring article much the same as many of the examples I've seen, all about links and implying HATEOAS is just about navigation, without saying it explicitly. The Wikipedia article was confusing: The Details section was just about links, once again, but it also included the quote "A REST client needs no prior knowledge about how to interact with any particular application or server beyond a generic understanding of hypermedia", suggesting HATEOAS is about discovery in general, not just links. However, your link "What does HATEOAS offer..." was very illuminating. Thanks – Simon Tewsi Jan 16 '16 at 22:27
2

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?

  • I like your analogies of Wikipedia and a Choose Your Own Adventure book, they make the concept quite clear. Thanks. – Simon Tewsi Jan 16 '16 at 4:00
1

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

  • Regarding your aside, I find the Richardson Maturity Model to be a good representation of the nuances of REST you can get. Of course, if you ask Fielding, the only true REST is one that enforces HATEOAS, but in practice, few teams bring their implementation to that level of rigor. – guillaume31 Jan 19 '16 at 12:19

Not the answer you're looking for? Browse other questions tagged or ask your own question.