HAL

The Hypertext Application Language application/hal+json (HAL) MUST be used as the representation format of a resource.

Introduction to HAL

HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API.

The HAL format is strictly coupled to HATEOAS. The main target of HATEOAS is to decouple the API Consumer from the paths used in the API. The API Client uses the links generated by our API instead of building them from the documentation. This is less error-prone for the API Consumer and it can allow making changes in the API without affecting the API Consumer code.

This document is an informal introduction to the HAL media type. For more details see HAL - Hypertext Application Language Specification.

HAL Document Object Model

HAL documents follow the object model defined in JSON-schema here.

IANA created a list explaining the standard relationships for REST. Do not forget to have a look here to find the role of each type of relation.

YAML code snippets are provided for OpenAPI Specification 2.0/Swagger and OpenAPI Specification 3.x.

Simple Document Example

The simplest Hal document looks like an empty JSON (it is an empty JSON!):

{
}

A document representing a "Greeting" resource might look like:

{
  "message": "Hello World!",
  "_links": {
    "self": {
      "href": "/greeting"
    }
  }
}

The field _links has a special meaning in HAL. It denotes a list of link relations - a pair of a relation identifier and a link (URI).

These link relations are used to express the relation of a resource with other resources.

In our case the "Greeting" resource isn't related to other resources but itself, hence the self relation pointing to the Greeting resource.

NOTE: It is customary for every resource representation to include the self link relation.

NOTE: The href MUST always be the relative path to the API root (e.g. without the host and scheme).

Relation Example

A more complex document example could be an "Order" resource that has a related resource "Author" (a person who created the order. It might look like:

{
  "_links": {
    "self": {
      "href": "/orders/1234"
    },
    "author": {
      "href": "/users/john"
    }
  },
  "orderNumber": 1234,
  "itemCount": 42,
  "status": "pending"
}

Embedding Example

Let's assume there is an "Orders" resource which is a collection of all orders from different authors. There is a relation between this Orders resource and possibly many other Orders resources.

We could express this in the _links object using the order relation, but sometimes it is practical to "embed" (entirely or partially) related resources representations in the originating resource representation. For a scenario like this HAL offers the _embedded field.

The _embedded field's object just contains the related resources HAL representations:

{
  "_links": {
    "self": { "href": "/orders" }
  },
  "_embedded": {
    "order": [
      {
        "_links": {
          "self": { "href": "/orders/1" }
        },
        "orderNumber": "1",
        "status": "pending"
      },
      {
        "_links": {
          "self": { "href": "/orders/2" }
        },
        "orderNumber": "2",
        "status": "cancelled"
      }      
    ]
  }
}

It is important to understand that embedded resource representation might be only partial and might also contain their own embedded resources.

The embedded resource representation should be used as a convenience function (e.g. to reduce the initial number of calls needed at application launch).

Where a full and up-to-date representation of a resource is needed the link relation should exercise the affordance (e.g. GET /orders/2).

Real-world Examples

Some APIs using HAL:

• Amazon AppStream REST API
• FoxyCart
• Clarify.io
• University of Oxford / Mobile Oxford

Working with HAL

Refer to the extensive list of libraries that work with HAL.

Java

Spring Framework

Spring framework supports HAL out of the box. More info can be found in Spring Documentation and examples.

Quarkus Framework

Quarkus framework supports HAL out of the box. More info can be found in Quarkus Documentation.

NodeJS

For working with HAL and Node.js using HALson npm package is suggested.