Skip to content

Latest commit

 

History

History
127 lines (91 loc) · 4.46 KB

hal.md

File metadata and controls

127 lines (91 loc) · 4.46 KB

HAL

The 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.

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 document follow the object model defined in JSON-schema here.

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 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 the relation between the Orders resource and possibly many Order 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:

Working with HAL

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

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

Spring Framework

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