Relationship and Difference Between HAL and HATEOAS

1. Overview

Web APIs have rapidly evolved with the rise of REST (Representational State Transfer). REST-based APIs allow developers to build powerful web applications that are modular, scalar, and loosely coupled. While RESTful APIs provide a solid foundation, they often lack the essential elements of discoverability and usability.

This is where HATEOAS (Hypermedia as the Engine of Application State) and HAL (Hypertext Application Language) can make a significant difference. Without HATEOAS, RESTful APIs become tightly coupled to the server, requiring hard-coded endpoints on the client side.

In this tutorial, we’ll explore the concepts of HATEOAS and HAL, their relationship, and their key differences.

2. Understanding HATEOAS

HATEOAS stands for Hypermedia as the Engine of Application State. To delve deeper into this concept, we first need to understand the meaning of Hypermedia. Hypermedia is an extension of hypertext that includes text links and other media types, such as images, audio, and video. It allows for rich interactions by enabling users to navigate related resources seamlessly.

HATEOAS enhances API interactions by embedding hypermedia links in responses. This enables clients to navigate and interact with resources dynamically without requiring prior knowledge of the API’s structure. It promotes loose coupling and allows APIs to evolve independently over time.

It means that client-server interactions should rely entirely on hypermedia received in the server’s responses. Each response from the server includes links that guide the client in discovering additional actions and resources along with the data.

Let’s understand more about HATEOAS with the help of a shopping cart example:

When a client requests details about a shopping cart with items, the server provides relevant links for possible actions:

GET /cart/12345 HTTP/1.1

HTTP/1.1 200 OK
{
  "cartId": 12345,
  "items": [
    {
      "id": 001,
      "name": "TV",
      "qty": 1,
      "amount": 4750
    }
  ],
  "totalAmount": 4750,
  "links": [
    {
      "rel": "self",
      "href": "/cart/12345"
    },
    {
      "rel": "addItem",
      "href": "/cart/12345/add"
    },
    {
      "rel": "removeItem",
      "href": "/cart/12345/remove"
    },
    {
      "rel": "checkout",
      "href": "/cart/12345/checkout"
    },
    {
      "rel": "clear",
      "href": "/cart/12345/clear"
    }
  ]
}

In the above example, the client can add or remove more items, proceed to checkout, or clear the cart. All these operations are based on the items available in the cart. The links key indicates the available operations.  Now, let’s consider an example of an empty shopping cart:

GET /cart/987 HTTP/1.1

HTTP/1.1 200 OK
{
  "cartId": 987,
  "items": [],
  "totalAmount": 0.0,
  "links": [
    {
      "rel": "self",
      "href": "/cart/987"
    },
    {
      "rel": "addItem",
      "href": "/cart/987/add"
    },
    {
      "rel": "checkout",
      "href": "/cart/987/checkout"
    },
  ]
}

Now, the client’s available actions are limited. Clients can add items to the cart or proceed to checkout, but they can’t clear or remove items since the cart is already empty. This hypertext tells us what is allowed and what is not.

3. Understanding HAL

HAL is a simple format that helps developers create hypermedia representations for RESTful APIs, supporting the HATEOAS principle. It defines a simple format that gives an easy, consistent way to hyperlink between resources in REST API.

Let’s take a look at the key concepts of HAL.

3.1. Links

HAL enables the inclusion of hypermedia links within the resource representation. The _links property lists links related to the resource. Each link includes a rel (relationship type) and a href that clients can use to interact with the API. The _links property also contains a self-link, which allows clients to access the current resource directly.

3.2. Embedded Resources

As the name suggests, embedded resources indicate that other resources are contained within a given REST resource. The _embedded property can hold related resources. This allows the client to access related information without making any additional requests.

3.3. State

HAL uses JSON or XML to encode the resource data and the associated links.

Now, let’s take a look at an example without HAL where the response from an API will look like this:

{
  "cartId": 12345,
  "items": [
    {
      "id": 001,
      "name": "TV",
      "qty": 1,
      "amount": 4750
    }
  ]
}

The above example doesn’t provide any links to related resources. Now, we’ll add HAL links to the response to make it a HAL-compliant example:

{
  "_embedded": {
    "items": [
      {
        "id": 001,
        "name": "TV",
        "qty": 1,
        "amount": 4750,
        "_links": {
          "self": { "href": "/items/001" },
          "update": { "href": "/items/001/update" }
        }
      }
    ] 
  },
  {
    "_links": {
      "self": { "href": "/carts/12345" },
      "addItem": { "href": "/cart/12345/item" },
      "checkout": { "href": "/cart/12345/checkout" }
    }
  }
}

In the above example, the main data is under the _embedded property. Here, the main data contains the list of items in the cart, with each item having its own _links.

4. Relationship Between HATEOAS and HAL

HATEOAS and HAL are closely related concepts in terms of RESTful API design. HATEOAS is a principle of REST that encourages using hypermedia links to let clients explore APIs dynamically. On the other hand, HAL is a specific format that helps implement this by standardizing how to represent resources and their connections via links.

Let’s take a look at the shopping cart example discussed earlier. When a client requests details about a shopping cart with items, the server responds with a HAL representation:

GET /cart/12345 HTTP 1.1

HTTP/1.1 200 OK

{
  "cartId": 12345,
  "items": [{
      "id": 001,
      "name": "TV",
      "qty": 1,
      "amount": 4500
    }],
  "totalAmount": 4500,
  "_links": {
      "self": { "href": "/cart/12345", "rel": "self" },
      "addItem": { "href": "/cart/12345/add", "rel": "addItem"},
      "checkout": { "href": "/cart/12345/checkout", "rel": "checkout" },
      "clear": { "href": "/cart/12345/clear" , "rel": "clearCart" }
  },
  "_embedded": {
      "offer": {
        "code": "DISCOUNT10",
        "discount": 10
      }
  }

In the above example, the _links section provides hypermedia links describing actions the client can take based on the current resource’s state. The rel field is critical because it defines the action that the link represents (e.g. self, addItem, checkout, etc). It’s used to describe the meaning of the link and how the client should interpret it in the context of the API’s state.

 The _embedded section contains related resources embedded directly within the main resource. It allows clients to access related data without making additional requests, reducing network calls and enhancing efficiency.

The resource’s state is captured in the actual data returned in the response, such as items and the total amount of the cart.

5. Key Differences Between HATEOAS and HAL

Let’s take a look at the key differences between HATEOAS and HAL:

6. Conclusion

In this article, we discussed HATEOAS and HAL. While HATEOAS outlines a principle for how a RESTful API should function, HAL provides a concrete implementation that simplifies hypermedia controls in APIs. Using HAL, developers can easily create HATEOAS-compliant APIs, which simplifies resource discovery and interaction for clients.

By combining HATEOAS and HAL, APIs become self-descriptive and discoverable. This results in better decoupling between clients and servers, allowing API to evolve independently over time.