REST Client Implementation Embracing HATEOAS Constraint?

Question

Does anybody know of an implementation of a REST client that embraces the constraint of Hypermedia as the Engine of Application State (HATEOAS)?

The Sun Cloud API seems to be a good candidate, judging from the way it's documented and a statement by the author to the effect that Ruby, Java, and Python implementations were in the works. But so far I've found no trace of the code.

I'm looking for anything - even a partial implementation would be helpful.

Honestly

Good question. I've also found no frameworks for writing RESTful clients: IE those that can react dynamically following the HATEOAS principle. It's a shame because this idea is a tenet of REST but the lack of formal support as well as a lot of misunderstanding about REST in general makes the community look fragmented. – Joanniejoao

@DawidFerenczy it is off-topic over there for the same reasons as it is here. Please abstain of recommending sites you're not familiar with. Recommended reading: What goes on Software Engineering (previously known as Programmers)? A guide for Stack Overflow – Ultramarine

Answer 1

The very first thing you should look at is the common web browser. It is the standard for a client that embraces HATEOAS (at least to some degree).

This is how Hypermedia works. It's so simple that it's almost painful:

1. you point your browser to http://pigs-are-cool.org/
2. the browser loads the HTML page, images, CSS and so on.
   • At this point, the application (your browsing experience) is at a specific URI.
   • The browser is showing the content of that URI
3. you see a link in the application
4. you click the link
5. the browser follows the link
   • at this point, the application is at a different URI
   • The browser is showing the content of the new URI

Now for a short explanation of how the two terms relate to the web browsing experience:

• Hypermedia = HTML pages with the embedded links
• Application state = What you're seeing in the browser at any point in time.

So HATEOAS actually describes what happens in a web browser when you go from web page to web page:

HTML pages with embedded links drive what you see in the browser at any point in time

The term HATEOAS is just an abstraction of this browsing experience.

Other examples of RESTful client applications include:

• RSS and Feed readers. They traverse links given to them by users
• Most AtomPub blog clients. They need merely a URI to a services document, and from there they find out where to upload images and blog posts, search and so on.
• Probably Google Gadgets (and similar), but they're merely browsers in a different skin.
• Web crawlers are also RESTful clients, but they're a niche market.

Some characteristics of RESTful client software:

• The client works with with any server, given that it is primed with some URI and the server responds with an expected result (e.g. for an atom blog client, an Atom services document).
• The client knows nothing about how the server designs its URIs other than what it can find out at runtime
• The client knows enough media types and link relations to understand what the server is saying (e.g. Atom or RSS)
• The client uses embedded links to find other resources; some automatically (like <img src=) some manually (like <a href=).

Very often they are driven by a user, and can correctly be termed "user agents", except for, say GoogleBot.

Manamanacle

That's all very good, but a web-browser merely renders the hypermedia, it's a human doing all the comprehension and deciding what links means and what things to click on. What about a client implementation designed to be driven by software? – Gibun

That is absolutely the big difference. A client implementation driven by software needs to be programmed to understand the links (and forms?) it finds on its "adventures". The main point is, I guess, to code a client towards media types, and not a particular server's URI structure. – Manamanacle

It's interesting that all your 'other examples' are clients which retrieve data and render it for a human to read. HATEOS works great on the server for exposing things in a logical format, but on the client side, i can't see what it offers over RPC. I just end up hardcoding the name of the links that interest me, instead of hardcoding the URL structure of those links. How does media type help me? I don't know the media type until i retrieve the link. – Gibun

Try and read this thread. 5 post from the top. They discuss Roy Fieldings blog post. The "client" be it human or machine should understand the media type. In the book REST In Practice they discuss resources vs media types. At one end you could define a media type for each resource or only have a single media type for all resources. But again the media type should define the actions etc. Yes if you use application/xml then you can't really do anything. – Untune

Answer 2

Restfulie is a Ruby, Java, and C# framework which aims to enable building clients and servers which employ HATEOAS. I haven't used it, but it does look interesting.

Here's some example code from their java project:

Order order = new Order();

// place the order
order = service("http://www.caelum.com.br/order").post(order);

// cancels it
resource(order).getTransition("cancel").execute();

Again, I'm not sure exactly what this does, or how well it works in practice, but it does seem intriguing.

Hypertrophy

Answer 3

The problem with REST HTTP and HATEOAS is that there is no common approach to specifying links so it is hard to follow links since their structure might change from a service provider to another. Some would use <link href="..." /> others would use proprietary structure for of links ex. <book href="..." />. It is not like in HTML or atom were link are part of a standard defined.

A client can't know what a link is in your representation is it doesn't know your media type unless there is a standard or conventional representation of a link

Engaged

Answer 4

The HATEOAS design principle (REST is a set of design principles also) means that each resource should have at most a single fixed URL.

Everything else related should be discoverable dynamically from that URL through "hypermedia" links.

I just started a wikipedia stub here

Ganiats

I think this answer and your Wikipedia stub are incorrect. I don't see how or why a REST application has to be accessed by a single simple URL. Any given URL should be bookmarkable (Cool URIs don't change) and I don't see how "at most a single fixed URL" makes sense. That implies that there are resources that don't have a URL? Obviously not. I don't see why a resource can't have multiple URIs either. HATEOAS means that state transitions are accomplished via hypermedia links. That includes going from some deep bookmark back up higher to some parent resource. – Territerrible

The HATEOS principle is actually one where the URI isn't fixed, that's the point. Decouple client url assumptions from servers real implementation. – Vacuous

When the state of the application changes, so might the operations available on it. Sure the value of HATEOS is that the links delivered are always valid for the application state that served it. – Hammock

Answer 5

In the meanwhile, there is the Spring HATEOAS project. It has also a client implementation: https://docs.spring.io/spring-hateoas/docs/current/reference/html/#client

Map<String, Object> parameters = new HashMap<>();
parameters.put("user", 27);

Traverson traverson = new Traverson(URI.create("http://localhost:8080/api/"), MediaTypes.HAL_JSON);
String name = traverson
    .follow("movies", "movie", "actor").withTemplateParameters(parameters)
    .toObject("$.name");

Makalu