Down to the Code in Rest Applications

Use HATEOAS to Separate Control Flow and Client Representation in Single Page Web Application

When it comes to “deliverythinking” sometimes we have to leave our flight level from 10,000 feets to somewhere closer to the actual code. This is at the end of the day what it’s all about: Code!

Few days ago I talked with a friend of mine with which I used to work for a long time. We used to develop web applications with Vaadin back in 2014 when we were working together. We discussed how Vaadin has evolved since then and how easy you can create new web applications with it now. In such discussion you end up talking about single page applications and millions of different java script frameworks around that at some point in time.  It is actually impressive, how single page web applications managed to dominate this topic despite of the huge number of different frameworks, tools and technologies.

But managing all this framework stuff in an enterprise world is another story.

In today’s article I want to point to another interesting thing with single page applications which I talked with my friend. When you develop single page application one big issue is to hide all the business logic and the presentation flow from the client tier. It must not be part of the java script code delivered to the client. This must be considered when you design an API. Ideally client does not know anything about business logic and control flow of the application.

In Rest Architecture there is a constraint principle called “ Hypermedia As The Engine Of Application State (HATEAOS)“. HATEOAS allows exactly this separation of control flow and client. “With HATEOAS [..] A REST client needs no prior knowledge about how to interact with an application or server beyond a generic understanding of hypermedia.” as Wikipedia explains.

With other words a rest resource comes with a list of links which tell the client next interactions are possible starting from this served resource.

As an example (Source Wikipedia) if you requested an bank account with

GET /accounts/12345 HTTP/1.1
Host: bank.example.com
Accept: application/xml
...

the response could be like

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: ...

<?xml version="1.0"?>
<account>
<account_number>12345</account_number>
<balance currency="usd">100.00</balance>
<link rel="deposit" href="https://bank.example.com/accounts/12345/deposit" />
<link rel="withdraw" href="https://bank.example.com/accounts/12345/withdraw" />
<link rel="transfer" href="https://bank.example.com/accounts/12345/transfer" />
<link rel="close" href="https://bank.example.com/accounts/12345/close" />
</account>

As you can see here from account with number 12345 you can perform deposit, withdraw, transfer or close. The linking piece between the client and the backend are the keys given in the rel part of the links.

Of course there is an XML as well as JASON support for HATEOAS.

{
"firstname" : "Dave",
"lastname" : "Matthews",
_"links" : [
{
"rel" : "self",
"href" : "http://myhost/people"
}
]
}

For good old java developers Spring provides a project called Spring HATEOAS which currently is in a prerelease phase.

Also you can find a set of best practices in API design at Microsoft Azure.