Is RESTful (HATEOAS ) practical for specialised clients?

Question

Is there a proof of concept client(ie web application) that represents a real-world application implemented using and taking advantage of the RESTful principles? All I could find are API browsers but the development of a real world application(ie a social network or ecommerce website) is quite different.

I've read Roy's work and related papers but I still can't gasp how to make the most of Restful in the client development. I always end-up storing state on the client or specialise the media/type rendering. For example the same resource(ie profile resource) is rendered differently based on context(ie on the homepage, on the product page or on the dedicated profile page) so farewell media-type -> code on demand rendering.

I really can't see any advantage(in the way I work) of HATEOAS over an API with well defined/auto-generated IDL (ie json hyper-schema).

My current conclusion is that only generic clients(ie google) can benefit from HATEOS not real-world/specialised applications. The specialised client development doesn't seem to take any benefit if your API is HATEOS-enabled instead of being IDL described.

Answer 1

While it's true that HATEOAS gives you URI flexibility, and human discovery of flows, the real benefit is using it as an encoding of resource state .

If you have a state machine associated with a resource, you will have some states that permit certain state transitions and not others.

The opportunity to effect a possible state transition is offered to REST clients via operations against resource URIs - using HATEAOS hypermedia, you can define the transitions by a known rel link name, and then include or exclude the rel links, depending on which transitions are permitted by the current state.

This means the logic of determining which transitions are valid is kept server side - the client can choose to hide or disable UI options depending on if the associated rel link is present.

Another reason to include or exclude a particular rel link may be related to the access control permissions offered to the current user. Simply exclude them if the current user isn't permitted to carry out the transition.

If you are not dynamically including or excluding rel links based on resource state and/or state of the authorized user, then your analysis of the pros cons is pretty spot on, because you are not using them for the real reason they were included. After all, the S in REST stands for state ! :)

Answer 2

HATEOS is a design philosophy / style / flavor and this is largely a matter of taste or a tradeoff between full-blown code gen and a hand-written API.

The key differentiating aspect of HATEOS is the way references are constructed to other resources in the API (namely, by a full URL). This removes a lot of the documentation burden that you might otherwise encounter if the API response only includes an ID (and not the full URL to the resource).

However, when you use HATEOS with JSON instead of XML you lose some of the other context (eg should I PUT or GET or POST to this endpoint?) and so you must supplement this with some other kind of metadata if you want to generate a client, or documentation for humans.

In my experience HATEOS APIs are much easier for humans to consume with simple REST clients (eg cURL) compared to a WSDL or IDL which assumes the client is using generated code and will never touch the API directly.

Tradeoffs

So why would you choose HATEOS vs WSDL or some other generated option?

The basic assumption for APIs (which is not always true) is that they will have many flavors of clients / consumers, possibly implemented in different languages. This means that over time, writing and updating clients is more work than writing the service.

If you or your business are going to maintain the API clients yourself then there is a cost tradeoff between generating code for all of the clients (WSDL, SWIG, etc.) or hiring a language-specific developer to maintain one.

Chances are a generated API client is not going to follow the idiomatic style for any given language, and the code is generally ugly. If these things matter to you then you will probably want a human to write the client code. If you don't care about this, then you can stop reading about HATEOS and use a WSDL or similar approach instead.

In case you do want to optimize for a human to consume the API, though, HATEOS succeeds because it conveys contextual information to a human, and this makes it easier to write clients without extensive API documentation.

Example

For an example of a HATEOS-like API take a look at the GitHub API . It is quite easy to browse with a REST client and once you learn how to authenticate you can find most of the things you want by following referenced data URLs. You will still need to reference the documentation for specific details and advanced use-cases (like POSTing data) but it is very easy to write a simple client for GitHub without pulling in a GitHub client library or reading the docs end-to-end.