REST HATEOAS - How does the client know link semantics?

Question

Imagine I have a fully implemented REST API that offers HATEOAS as well.

Let's assume I browse the root and besides the self link two other links (e.g. one for /users and one for /orders) are returned. As far as I have heard, HATEOAS eliminates the need for out-of-band information. How should a client know what users means? Where are the semantics stored?

I know that is kind of a stupid question, but I really would like to know that.

Eirena

'How should a client know what "users" means?' That is a very good question. IMHO the whole HATEOAS concepts breaks on this question. The semantic can not be transported in-band. So where is the gain of in-band links? – Shaffert

I agree. The "Emperor" is not wearing any underwear. – Marishamariska

Thanks for your contributions! :) – Eirena

This is not a stupid question. This is something conveniently ignored by many. – Saladin

Answer 1

Suppose you've just discovered Twitter and are using it for the very first time. In your Web browser you see a column of paragraphs with a bunch of links spread around the page. You know there's a way to do something with this, but you don't know specifically what actions are available. How do you figure out what they are?

Well, you look at the links and consider what their names mean. Some you recognize right away based on convention: As an experienced Web user, you have a pretty good idea what clicking on the "home", "search" and "sign out" links is meant to accomplish.

But other links have names you don't recognize. What does "retweet" do? What does that little star icon do?

There are basically two ways you, or anyone, will figure this out:

1. Through experimentation, which is to say, clicking on the links and seeing what happens, then deriving a meaning for each link from the results.

2. Through some source of out-of-band information, such as the online help, a tutorial found through a Google search or a friend sitting next to you explaining how the site works.

It's the same with REST APIs. (Recall that REST is intended to model the way the Web enables interaction with humans.)

Although in principle computers (or API-client developers) could deduce the semantics of link relations through experimentation, obviously this isn't practical. That leaves

1. Convention, based on for instance the IANA 's list of standardized link relations and their meanings.

2. Out-of-band information, such as API documentation.

There is nothing inconsistent in the notion of REST requiring client developers to rely on something beyond the API itself to understand the meaning of link relations. This is standard practice for humans using websites, and humans using websites is what REST models.

What REST accomplishes is removing the need for out-of-band information regarding the mechanics of interacting with the API. Going back to the Twitter example, you probably had to have somebody explain to you at some point what, exactly, the "retweet" link does. But you didn't have to know the specific URL to type in to make the retweet happen, or the ID number of the tweet you wanted to act on, or even the fact that tweets have unique IDs. The Web's design meant all this complexity was taken care of for you once you figured out which link you wanted to click.

And so it is with REST APIs. It's true that in most cases, the computer or programmer will just need to be told what each link relation means. But once they have that information, they can navigate through the entire API without needing to know anything else about the details of how it's all put together.

Microcurie

Thank you so much for your great explanation! So basically it's all about making the client independent from API changes, correct? Assume I browse the root and a JSON is returned that contains something like: {"links":[ { "orders" : "someIP/orders" }]} Then the client "knows" (because somehow I have to let a client know about the semantics of the term "orders") that it can find the resource at that link. And in case the link changes, it is still able to find the orders. I hope I have written this in an understandable way :) – Eirena

Yes, that's correct. The Twitter analogy works here as well: Twitter actually did majorly restructure their website in the past year or so, moving a lot of the implementation off the client and back onto the server, changing many of the site's URLs. But because the Web requires you to know only the meaning of (for instance) "retweet" and not the mechanics of it, everybody was able to continue using the site as though nothing had happened at all. – Microcurie

I should be clear: To my knowledge shielding clients from changes in the API's implementation is not a specific design goal of REST, but it is certainly a very useful result of adopting HATEOAS for your API. – Microcurie

Alright - thank you very much for your fast help! :) – Eirena

"in your web browser you see" - you are a user, and may be able to deduce what a link represents. An application cannot. HATEOAS is nothing more than another attempt at creating a semantic web. For actual machine-to-machine interaction, it is just useless overhead. – Machiavelli

Answer 2

REST doesn't eliminate the need for out-of-band information. You still have to document your media-types. REST eliminates the need for out-of-band information in the client interaction with the API underlying protocol.

The semantics are documented by the media-type. Your API root is a resource of a media-type, let's say something like application/vnd.mycompany.dashboard.v1+json, and the documentation for that media type would explain that the link relation users leads to a collection of application/vnd.mycompany.user.v1+json related to the currently authenticated user, and orders leads to a collection of application/vnd.mycompany.order.v1+json.

The library analogy works here. When you enter a library after a book, you know how to read a book, you know how to walk to a bookshelf and pick up the book, and you know how to ask the librarian for directions. Each library may have a different layout and bookshelves may be organized differently, but as long as you know what you're looking for and you and the librarian speak the same language, you can find it. However, it's too much to expect the librarian to teach you what a book is.

Uzziel