Rest – What’s the point with HATEOAS on the client-side

client-serverhateoasrest

As I currently understand HATEOAS is basically all about sending together with each response links with information about what to do next. One simple example is easily found on the internet: a banking system together with an account resource. The example shows this response after a GET request to an account resource

GET /account/12345 HTTP/1.1 HTTP/1.1 200 OK 
<?xml version="1.0"?> 
<account> 
    <account_number>12345</account_number> 
    <balance currency="usd">100.00</balance> 
    <link rel="deposit" href="/account/12345/deposit" /> 
    <link rel="withdraw" href="/account/12345/withdraw" /> 
    <link rel="transfer" href="/account/12345/transfer" /> 
    <link rel="close" href="/account/12345/close" /> 
</account>

Together with the data there are links telling what can be done next. If the balance is negative we have

GET /account/12345 HTTP/1.1 HTTP/1.1 200 OK 
<?xml version="1.0"?> 
<account> 
    <account_number>12345</account_number> 
    <balance currency="usd">-25.00</balance> 
    <link rel="deposit" href="/account/12345/deposit" /> 
</account>

So that we can only deposit. That's all fine, if we are using Fiddler or making requests with the browser we can easily see what can be done. This kind of information is useful then for us to discover the API's capabilities and the server is decoupled from the client.

The point, however, is that when we build a client, like a SPA with Javascript, or an Android app or many other things, I can't see how HATEOAS continues being relevant. What I mean is the following: when I'm coding the SPA in javascript, I must know what can be done in the API in order to write the code.

So I need to know the resources, the methods supported, what they expect to receive and what they give back in order to write the ajax calls to the server and even in order to build the UI. When I build the UI, I must know that after requesting the account, one can for example deposit into it, or I won't be able to provide this option on the UI. Also, I'll need to know the URI to make the deposit to build the ajax call.

What I mean is, when we make requests to the API, links do allows us to discover and use the API better, but when we build a client, the app we are building won't simply look at the links and then by itself render the correct UI and make the right ajax calls.

So, how is HATEOAS important for the clients? Why do we bother with HATEOAS anyway?

Best Answer

the app we are building won't simply look at the links and then by itself render the correct UI and make the right ajax calls

In fact, this is exactly what HATEOAS will give the UI. Not what is possible, but when it is possible. A formal HATEOAS like HAL, as the question states, gives links that indicate what is possible. But when those links show up depends on the state of the application. So, the links can change on the resource over time (based on actions that have already been performed).

This allows us to build a UI that contains all the possible states, but not be concerned with when those states become active. For example, the presence of the rel="deposit" can directly tell the UI when it is OK to render the make deposit form. Which then allows the user to enter a value and submit using the link.

Related Topic