HATEOAS and Why It’s Needed in RESTful API?

HATEOAS stands for Hypermedia as the Engine of Application State and it is a component of RESTful API architecture and design. With the use of HATEOAS, the client-side needs minimal knowledge about how to interact with a server. This is made possible by the network application responding to the client’s requests with dynamically generated information through the use of hypermedia.

When accessing a webpage through a browser, users have the ability to interact with the webpage by using buttons, inputs, clicking on links, etc. However, traditional API responses have no such functionality present to allow an application to interact with the server through the response. HATEOAS acts as a way to address this. A HATEOAS request allows you to not only send the data but also specify the related actions.

Application State Change Through HATEOAS

When using HATEOAS architecture, a client will be able to access the API for a network application through a simple, static, RESTful URL call. Now, any further actions, that the client may wish to take, will be enabled by the data, returned by the server, in the original call. This will enable the client to move from one application state to the next just by interacting with the details contained in the responses by the server. 

The “data”, within the response, that enables this change of state is simple hypermedia links. This is how HATEOAS manages the change in application states through hypermedia.

Demonstration of the Use of HATEOAS

As an example, consider that a client wants to interact with a network application to fetch details of employees’ payroll within an organization. The RESTful call to enable this would be as follows:

GET /payroll/employee_123 HTTP/1.1

The server will respond with a JSON containing the required details. Additionally, the response will contain hypermedia links that allow the client to take further actions. As an example, consider the response by the server is as follows.

HTTP/1.1 200 OK
Content-Type: application/+json
Content-Length: ...
{
   "payroll": {
       "employee_number": "employee_123",
       "salary" : 1000,
       "links": {
           "increment": "/payroll/employee_123/increment",
           "decrement": "/payroll/employee_123/decrement",
           "close": "/payroll/employee_123/close"
       }
   }
}

We can observe that, in addition to the expected information being received in the response, additional information is presented in the form of RESTful hypermedia calls under the “links” title. These links allow further interaction with the server by incrementing or decrementing the salary or closing the account. It may be noted that these links correspond to the respective API endpoints to increment, decrement, and close the payroll account. Also, these links are pre-populated with the employee identifier. This means that such content is dynamically generated. 

An additional example of how these hypermedia links are dynamically generated can be demonstrated is as follows: 

Assume that for a given employee, the account has been closed. Thus, the increment and decrement methods are irrelevant to such an account. Thus, hitting the payroll endpoint for such an employee would result in response as follows:

HTTP/1.1 200 OK
Content-Type: application/+json
Content-Length: ...
{
  "payroll": {
      "employee_number": "employee_123"
      "links": {
          "start": "/payroll/employee_123/start"
      }
  }
}

In this case, the links have changed to include functions that are relevant to the current state only. Thus, the only action made available is to “start” the payroll for such an employee.

Need for HATEOAS

With traditional, non-HATEOAS based API systems, the API endpoints need to be hard-coded within the client-side application. Any changes to this endpoint would result in the client application systems breaking down. Thus, such changes would need to be updated in each of the client’s applications. This system is, therefore, tightly coupled.

With HATEOAS, the system becomes loosely coupled as the URLs do not require hard-coding. Instead, the URLs are generated on the fly on the server-side and supplied to the client through the JSON responses. Clients can now use these URLs from the response and be sure that these URLs are the latest versions. 

tabmir

Follow

Improve

Article Tags :

• Web Technologies