Does discoverability in HATEOAS require the information must be machine readable, or can it just be human readable?

Question

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)?

Answer 1

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