REST WEB SERVICES

HATEOAS - Important Concept For Designing

HATEOAS (Hypermedia as the Engine of Application State) is a constraint of the REST application architecture that keeps the RESTful style architecture unique from most other network application architectures. The term “hypermedia” refers to any content that contains links to other forms of media such as images, movies, and text.

Now what does it mean and why this is important. It's a well agreed belief that a good written software is the one which has a good documentation. But there is little deviation in this belief when it comes to the Rest API. A Rest API is said to be perfect if it doesn't need any documentation at all. It should be so crystal clear to the developer who is consuming the service that he/she should not even refer to the documentation. It should be designed like a website, like once we go to the Home page we can navigate to the different resources with the help of hyperlinks.

Now the question is how to achieve this? The simple answer is providing as much related links as possible about the resource in the response. Lets take the case of our registration application.

The typical response of the students resource /myApp/students/1:

<Student>
    <rollno>10</rollno>
    <firstName>Surabhi</firstName >
    <lastName>Sahu</lastName>
    <age>25</age>
</Student>

What if we give the additional information to the client, about how to check all the courses that this student (with the given roll no.) has enrolled into.

<Student>
    <rollno>10</rollno>
    <firstName>Surabhi</firstName >
    <lastName>Sahu</lastName>
    <age>25</age>
    <link rel = “courses” href =”/myApp/students/1/registrations”>
</Student>

Now this will be very useful to the client as he will directly get the courses enrolled resource URI information from the students response itself. This is a HATEAOS concept.

We can also include more options like, URI to Update student information, Delete the student data etc.

Similarly for the courses URI: /myApp/courses/1234

<Courses>
    <CourseID>1234</ CourseID>
    <CourseName>REST</ CourseName>
    <CourseFess>50000</ CourseFess>
    <courseDuration>30</CourseDuration>
    <courseStartDate>27-09-2017</courseStartdate> 
</Courses>

Now once, a client has the course information, he/she might want to know about the students who have enrolled for the course, we can send the link of the resource URI of the students enrolled in this course.

<Courses>
    <CourseID>1234</ CourseID>
    <CourseName>REST</ CourseName>
    <CourseFess>50000</ CourseFess>
    <courseDuration>30</CourseDuration>
    <courseStartDate>27-09-2017</courseStartdate>
    <link rel=”students” href=”/myApp/courses/1234/registrations”> 
</Courses>				

So HATEOAS is a concept to provide links of the related sub resources to the resource which is requested by the client so that is becomes easier for the client to make further calls to the REST API.

We will learn in the coming lessons how to achieve this but keep this in mind this is an important design aspect and should be implemented very carefully.

So always remember,

A GOOD REST API DOES NOT NEED ANY DOCUMENTATION