What is the benefit of hypermedia (HATEOAS)?

Question

I don't understand the benefit to HATEOAS for APIs intended for use by programs (as opposed to humans directly browsing your API). Sure, the customer isn't bound to a URL schema but they are bound to a data schema which is the same thing in my mind.

For example, assume I want to view an item on an order, let's assume I've discovered or know the order URL already.

HATEOAS:

order = get(orderURL);
item = get(order.itemURL[5]);

non-HATEOAS:

order = get(orderURL);
item = get(getItemURL(order,5));

In the first model I have to know the fact that the order object has an itemURL field. In the second model I have to know how to construct an item URL. In both cases I have to "know" something ahead of time so what is HATEOAS actually doing for me?

Answer 1

One difference is that the schema is hopefully a standard, or at least can be reused by others.

For example, let's say you're using the Twitter API and you want to support StatusNet too (or instead). Since they use the same data model as Twitter, if the API follows HATEOAS you now just have to change the main URL. If it doesn't, you now have to change each single URL from the code.

Of course, if you need to change the code to put the service's entry point URL anyway, it might not seem so helpful. It really shines is if that URL is dynamically inserted; for example, if you were building a service like Twillio, which would interact with the user's own API.

Answer 2

1. Explorable API: It may sound trivial but do not underestimate the power of an explorable API. The ability to browse around the data makes it a lot easier for the client developers to build a mental model of the API and its data structures.

2. Inline documentation: The use of URLs as link relations can point client developers to documentation.

3. Simple client logic: A client that simply follows URLs instead of constructing them itself, should be easier to implement and maintain.

4. The server takes ownership of URL structures: The use of hypermedia removes the client's hard coded knowledge of the URL structures used by the server.

5. Off loading content to other services: Hypermedia is necessary when off-loading content to other servers (a CDN for instance).

6. Versioning with links: Hypermedia helps versioning of APIs.

7. Multiple implementations of the same service: Hypermedia is a necessity when multiple implementations of the same service exists (and one client needs to access more than one of them).

You can find an in-depth explanation of these bullet points here: http://soabits.blogspot.no/2013/12/selling-benefits-of-hypermedia.html