good use case of HATEOAS

Question

may I have some example/typical use case of HATEOAS? I agree it can be a very powerful concept provide great flexibility but I am not sure how to properly get benefit from HATEOAS. would be great if you can share your experience/use case.

Ferrocyanide

Answer 1

A good answer from @dreamer above, but HATEOAS is not present in most REST-based services. It is a constraint on the REST architecture style that allows clients to interact with a service entirely via the hypermedia contained in the resources.

If you look at the Twitter or Facebook REST APIs, you won't find hypermedia. Look at the Facebook friendlist resource. There are no hypertext links in that resource that you can use to transition the state of the resource - to delete, update, etc. Instead, you need to read the out-of-band documentation to understand what you need to do to delete that resource.

One of the claimed advantages of using hypermedia in your APIs is that you can manage change within the resources themselves. For example, what if Facebook wanted to add additional functionality to the frendlist? If it were built with HATEOAS in mind, the resource would be updated to add the hyperlinks provides those additional state transitions.

If this sounds difficult, you're right. But as a developer of client applications, however, once you understand how the hypermedia is presented, you can build applications that will evolve along with the API itself.

So how do you build APIs using HATEOAS? A number of options are out there, but I like the Hypertext Application Language (HAL) the best.

UPDATE: Since you asked for an example, here's a link to a demo using HAL.

Afro

There are no links to delete or update, partly because those don't need to exist in REST. That's RPC-style thinking. The URL for the resource itself should be all you need to know, because there are already built-in methods to PUT or DELETE a resource. – Wafture

Yep, good point. But what if the resource allowed for other state transitions? That's where hypermedia plays a role. Like an commerce application that allows you to place an order? How would you know how to pay for that? Include a hyperlink to a payment resource would solve that. Thanks for the comment. – Afro

You'd refuse to accept the order until it included payment information or some proof that a payment had been made. – Wafture

Yes, that's one way to solve that particular problem. But the question was asked about HATEOAS. And if you follow this approach, it requires that consumers of the API can follow an application protocol (in this simple example, ordering and paying for a product) by using the hypermedia returned by the server. – Afro

It requires only that consumers of the API not need to know beforehand what URLs to use. Given an entry point, it should be possible to navigate using only information provided in-band. But only if navigation makes sense! A list of friends, for example, should include a URL for each friend. But the checkout process is inherently stateful, which is frowned upon in REST anyway. – Wafture

REST is all about state transitions. It's in the name! ;) Here, the transition is from order placed to order purchased. – Afro

REST stands for REpresentational State Transfer. State transitions (aside from deletion or replacement of a resource with a new one, or posting new resources) are not really part of the spec; you shouldn't even have server-side state that doesn't represent a valid resource and have a URL. – Wafture

Applications have state, and clients interacting with resources defined in an API drive state transitions. HATEOAS describes a mechanism for instructing the client within the context of the resource itself on how to make those transitions. – Afro

That's part of my point, though. RESTful applications are stateless. That's one of the rules. Either it's a full-fledged resource, or it's not maintained server-side. – Wafture

State transitions are supposed to be documented by the media type. – Geniagenial

cHao, Not sure where we disagree. REST interactions are stateless because the HTTP protocol is stateless. And that's why we have additional work to do to manage state in web applications. Pedro, HAL solves the same problem without having to create a custom media type. You even mentioned HAL in your answer (with a link to the HAL browser I already provided). – Afro

@PeterB: We disagree on who's responsible for maintaining partial state. I believe the order is a resource, and an incomplete order is an invalid resource (because it's worthless until it has all the info needed for processing, including payment info). On those grounds, a truly RESTful application must refuse an incomplete order at the HTTP level. Of course, it should tell the client why. But the client is ultimately responsible for fixing the order on its end and resubmitting the order. Otherwise, you're violating the statelessness constraint. – Wafture

@cHAo. The Client maintains application state. The Server maintains resource state. There should be no room for disagreement. – Afro

@PeterB: I agree that there should be no room for disagreement. That's why i find it odd that you're disagreeing with me on this. :) If an invalid order is a "resource", there's no significant difference between storing it and storing the session variables that would be used to construct it. In both cases, the server is storing intermediate state -- which belongs to the application until it can be used to construct a valid resource. The biggest benefits of REST come from getting the server entirely out of the business of doing that. – Wafture

If you look at the Twitter API you will not find Hypermedia, because they don't call their API as REST. You will not find a single instance of the acronym REST in their documentation. Twitter has API, not REST API. – Selfhelp

Answer 2

Good public HATEOAS use cases are hard to find, because there are a lot of misconceptions around REST, and HATEOAS can be hard to implement. You really need to have a good understanding of its benefits, before you're willing to put yourself through the trouble of getting it to work, and if the clients don't follow it correctly, all work will be in vain.

From my experience, implementing proper REST in a company is a culture change as important as moving to version control systems or agile development. Unless everyone adopts it and understands it, it causes more trouble than it solves.

Having that in mind, I think the best example one will find is the foxycart.com HAL API, on the link below:

https://api-sandbox.foxycart.com/hal-browser/hal_browser.html#/

Geniagenial

Answer 3

It's very powerful concept used in RESTful presentation of the application to the client. There are many many projects which are adopting this interface now. A typical use case for this is Web Services APIs using RESTful APIs. A RESTful APIs typically consists of the following elements:

• base URI, such as http://example.com/resources/
• an Internet media type for the data. This is often JSON but can be any other valid Internet media type (e.g. XML, Atom, microformats, images, etc.)
• standard HTTP methods (e.g., GET, PUT, POST, or DELETE)
• hypertext links to reference state
• hypertext links to reference related resources

The application state can be modified using above HTTP methods for example, to get a particular resource, A client can issue a REST query using curl like:

curl -X GET --url "http://example.com/resource/" -X "Content-Type:application/json"

you could go through the man pages for curl and its usage. More on RESTful interface concepts can be looked upon at wiki

Heraclitus

Thanks for the explain, but do you have any specific example/experience to share? At this staging I am more after examples case that HATEOAS make good sense while designing the restapi – Ferrocyanide

@John, see media.relayhealth.com/documents/…. Section 8 describes a hypermedia-enabled REST API. – Afro