5

I'm trying to understand the concepts of HATEOAS (Hypermedia As The Engine Of Application State) in REST. The following have been very useful:

What does HATEOAS offer for discoverability and decoupling besides ability to change your URL structure more or less freely?

REST APIs must be hypertext-driven (from Roy Fielding himself)

From them I understand that HATEOAS isn't just about providing links to tell a client what the next valid actions are, it's also about providing information about the valid methods that can be applied to a resource, and the format of the data being passed in both directions between the client and the server.

It's the data format that I'm having trouble with. Roy Fielding mentions defining new media types to describe the data formats. If new media types have to be created for every API anyone creates there would be hundreds of thousands of single-use media types defined.

To get around this issue, someone suggested using the HAL (Hypertext Application Language) media type for RESTful APIs. HAL includes the concept of CURIEs, prefixes for relation names that expand into URLs that point to documentation.

For example,

"_links": {
  "curies": [
    {
      "name": "doc",
      "href": "http://haltalk.herokuapp.com/docs/{rel}",
      "templated": true
    }
  ],

  "doc:latest-posts": {
    "href": "/posts/latest"
  }
}

Here the relation name is doc:latest-posts where doc is a CURIE that expands to http://haltalk.herokuapp.com/docs/, and http://haltalk.herokuapp.com/docs/latest-posts will point to documentation about the latest-posts resource (note that the URL to the latest-posts resource itself, as opposed to the documentation about it, is /posts/latest)

This seems a good way for client-side developers to learn about each resource provided by the API. But does having an automatic link to human readable documentation satisfy the discoverability requirements of HATEOAS? Or must the information describing the data formats required for each resource be machine readable (eg a custom media type for the API)?

  • What do you mean by "machine readable" ? That a machine has all it needs in the response to construct the next request to follow one of the links ? Or that the machine is able to determine by itself which link to follow next ? – guillaume31 Jan 19 '16 at 15:23
  • @guillaume31: By "machine readable" I was thinking of data or meta-data that can be interpreted by a client application. Examples: (1) Including a well-known media type in the response header that would define the format of data the client should send; (2) Sending links via a Link header that include well-known relation names so the client can determine what its next action is (choose an option based on a relation name it recognizes, then use the link associated with that relation name for the next request). – Simon Tewsi Jan 20 '16 at 1:35
2

As you pointed out, Roy Fielding wrote an interesting article on his blog. And this paragraph summarize pretty well "How to HATEOAS":

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

So, yes HATEOAS rely on providing links to clients to drive them on the application. A typical example is, as part of a banking application, a banking account where you have a link to withdraw and an other link to make a deposit. If your balance is negative, the withdraw link will disappear. That's HATEOAS: you provide links to help the client.

But, wait a minute. In the quoted paragraph, Fielding talks about descriptive effort, media type and out-of-band information... interesting :-) ! In fact, HATEOAS is not just providing links, because it's not sufficient for a client to have only meaningless links. How the client is supposed to know the verbs to invoke when following on a link ? (GET/POST/PUT ?) ... How the client is supposed to know the data to pass as parameter when following a link ? If the client don't know these informations, it's simple: your client rely on out-of-band information (and that's baaaaaad!)

Here comes the interesting part: how can the client get this information? Answer: through self-descriptive message and the media-type used ! That's how you make HATEOAS: you fully (not just with providing links!) drive the client with links and self-descriptive message.

Depending on your application, you may have to define your own media type that will accurately describe your message. Some other exist,s they are called "hypermedia format". HAL is one of them but has some limitations. An outdated comparison can be found here: https://github.com/kevinswiber/siren/issues/15

Personally, I suggest you take a look at Hydra, that would probably be a W3C standard and has a lot of features. For example, you can define what operations are possible on a link (= which verbs to use, which data to pass as parameter, if it required or not, etc...). Some nice presentations can be found there: http://www.hydra-cg.com/

To conclude: I would say that HATEOAS is related to machine readable. By self-describing the message you give the ability to any machine to understand your API. Because human readable could involve out of band knowledge and that's typically what is not RESTful (nor HATEOAS compliant).

  • The OPTIONS method lets the client know which verbs are accepted by the server on a given resource :) – guillaume31 Jan 19 '16 at 15:17
  • I was pretty sure that someone would comment about OPTIONS verb :D. But you right! Although my response is mainly focusing on self-descriptive message and the benefits to have it ! (in this case, you don't really need of this verb) – AilurusFulgens Jan 19 '16 at 15:47
  • @AilurusFulgens: Both your links are very interesting, thanks. I've just spent a couple of hours reading the linked documents. Hydra seems very complete but also more complicated to parse (for both a human and a machine) compared to HAL or Siren. HAL is very simple, basically just links but also links to documentation, whereas Siren seems to sit in the middle between HAL and Hydra. – Simon Tewsi Jan 20 '16 at 3:27
  • 1
    @SimonTewsi It depends on your needs. HAL might be sufficient. Siren has the actions metadata that is the most interesting feature. Hydra is more complex because it requires some basic knowledge about semantic web (because Hydra is based on JSON-LD format, and JSON-LD is related to LinkedData!). Take a look at this video presentation of Hydra: youtu.be/91wSt3fHWLE . You could see that your question about HATEOAS involves a lot of more concepts than just "linking" finally ;-) ! It depends on what you need, again. – AilurusFulgens Jan 20 '16 at 9:12

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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