HATEOS in Rest Service - Everything You Need to Know

HATEOAS ( Hyper Media As The Engine Of Application State) is one of the six constraints of Restful API that helps a Rest client self discover related REstful API , given just the entry point. With HATEOAS, the client is freed from hardcoding any API endpoints. It works in synonym with a web page browsing, where given the root domain, the user can explore all the parts of the website, without remembering sub URLs.

Let's explore this :

You visit a an eCommerce website, you get to know this site's URL, by some means. You might have book marked it or used a search Engine.

From this point, is there any reason for you to go to the bookmark or search Engine to see the product pages of eCommerce, or the shopping cart? It should not be. HATEOAS (pronounced as "hey-tious") is in action.

HATEOUS in Rest

Programmatically, it means that if you are returning a JASON object as the result from your service, it must also have a section that covers the related Services.

Pros of HATEOUS

HATEOUS is a Restful constraint, and if your client expects that conformity, it will be a fair expectation. Moreover, HATEOUS provides many advantages.

  1. No URL Hardcoding at Client
    •  Client is given the related service URLs which means, there is no need for the client to remember it. If this is not the case client will have to hardcode such details or at least have it in a config file or database. With HATEOAS there is no such need.
  2. Client is from many application logic
    • When the service returns the related service, it can imply that it contains only those service the client has access to. There is no need for the client to check next service it has access to. Many such logics could be resolved at server side and client is made thinner.
  3. Versioning is smooth  
    • If the related services goes through an upgrade and by change its URLs gets versioned, client readily has it. However, it must be noted that simply having the next version of URL will not solve all the issues, as client need to understand the change in the  response as well. However, at least a part of the problem is solved here.
  4. Usage Tracking and Correlation is Easier 
    • A natural sequence of call is established and this makes Tracking and correlation easier. How called which service and what was the previous call etc. is easier to track.
  5. Enforces Clean Design
    • The services needs to identify the related services to include it in the response. This enforces that there is no complex sequence as much as possible. Design needs to consider this and take care of it.
  6. Ease 
    • Automation in the code and many such possibilities makes it easy for the client. Okay, I got the account details, am allowed to deposit? - yes of course, here is the URL.
  7. Your Service is Truly Restful
    • This is a Rest Constraint and implementing is makes you service Truly Restful

Cons of HATEOUS

Implementing HATEOUS comes with its own challenges.

  1. Hard 
    • From Design to implementation it is hard - you client is dependent on each service to show the dependency, so need to cover all those.
  2. More work at the Server Side
    • More coding time, more coordination between services, the good things of HATEOAS comes with additional work.
  3. Client is dictated by the Server
    • Server needs to have a good understanding of the client uses cases. Since client is dictated by the server what to do next, it could limit certain Use Cases, and all of them are hard to predefine
  4. Lots of Unnecessary Data in the Response
    • Client may not use all the next services which results in lots of unnecessary data, if you have many related services.
  5. May End up in Over Designing
    • Sure it enforces clean design, but you may tend to overdesign also, since you may try to cover all the scenarios client may be in.
  6. Complex Navigation is hard to represent
    • Correlating with website browsing, you can go from home page to first level page. You may also be able to go from home page to inner pages. Representing and identifying such things could get complex unless attention is given during design time

HATEOAS and HAL

HATEOAS is the constraint and HAL (Hyper Text Application Language) is the standard how to do it. It is possible to represent HATEOAS using JASON or XML using HAL

Conclusion

HATEOAS is an important constraint of REstful API and it adds many advantages to it. However, it comes with a overhead of additional design, coding and complexity. When in crunch, it will still be acceptable to implement a service without HATEOAS if service provider and clients can come to an agreement. Yes, your service is not fully Restful, but all parties are in agreement.

{"email":"Email address invalid","url":"Website address invalid","required":"Required field missing"}