HAL - Hypertext Application Language

A lean hypermedia type

Summary

HAL is a format you can use in your API that gives you a simple way of linking. It has two variants, one in JSON and one in XML.

RFC

The JSON variant of HAL (application/hal+json) has now been published as an internet draft: draft-kelly-json-hal.

Libraries For Working With HAL

Example Hypermedia API using HAL

Discussion Group

If you have any questions or feedback, you can message the HAL-discuss mailing list.

General Description

HAL provides a set of conventions for expressing hyperlinks to, and embeddedness of, related resources - the rest of a HAL document is just plain old JSON or XML.

Instead of using linkless JSON/XML, or spending time developing a custom media type, you can just use HAL and focus on defining and documenting the link relations that direct your clients through your API.

HAL is a bit like HTML for machines, in that it is generic and designed to drive many different types of application. The difference is that HTML has features for presenting a graphical hypermedia interface to a 'human actor', whereas HAL is intended for presenting a machine hypertext interface to 'automated actors'.

For a pracitcal introduction to hal+json you can read this article: JSON Linking with HAL

The HAL Model

HAL has two main components: Resources and Links. * Resources can have their own state, links, and other embedded resources. * Links have a link relation (rel) that signals how to interpret the target resource.

Below is an image that roughly illustrates how a HAL representation is structured:

The HAL Information model

Examples

Here is how you could represent a collection of orders with the JSON variant of HAL:

{
    "_links": {
        "self": { "href": "/orders" },
        "next": { "href": "/orders?page=2" },
        "find": {
            "href": "/orders{?id}",
            "templated": true
        },
        "admin": [{
            "href": "/admins/2",
            "title": "Fred"
        }, {
            "href": "/admins/5",
            "title": "Kate"
        }]
    },
    "currentlyProcessing": 14,
    "shippedToday": 20,
    "_embedded": {
        "order": [{
            "_links": {
                "self": { "href": "/orders/123" },
                "basket": { "href": "/baskets/98712" },
                "customer": { "href": "/customers/7809" }
            },
            "total": 30.00,
            "currency": "USD",
            "status": "shipped"
        }, {
            "_links": {
                "self": { "href": "/orders/124" },
                "basket": { "href": "/baskets/97213" },
                "customer": { "href": "/customers/12369" }
            },
            "total": 20.00,
            "currency": "USD",
            "status": "processing"
        }]
    }
}

Here is the same example using the XML variant of HAL:

<resource href="/orders">
  <link rel="next" href="/orders?page=2" />
  <link rel="find" href="/orders{?id}" templated="true" />
  <link rel="admin" href="/admins/2" title="Fred" />
  <link rel="admin" href="/admins/5" title="Kate" />
  <currentlyProcessing>14<currentlyProcessing>
  <shippedToday>20</shippedToday>
  <resource rel="order" href="/orders/123">
    <link rel="customer" href="/customers/7809" />
    <link rel="basket" href="/baskets/98712">
    <total>30.00</total>
    <currency>USD</currency>
    <status>shipped</status>
  </resource>
  <resource rel="order" href="/orders/124">
    <link rel="customer" href="/customer/12369" />
    <link rel="basket" href="/baskets/97213">
    <total>20.00</total>
    <currency>USD</currency>
    <status>processing</status>
  </resource>
</resource>

How to use HAL

HAL is two media types (application/hal+json & application/hal+xml) with which applications are exposed as sets of link relations.

HAL encourages the use of link relations to:

Compliance

An implementation is not compliant if it fails to satisfy one or more of the MUST or REQUIRED level requirements. An implementation that satisfies all the MUST or REQUIRED level and all the SHOULD level requirements is said to be "unconditionally compliant"; one that satisfies all the MUST level requirements but not all the SHOULD level requirements is said to be "conditionally compliant."

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Media Type Identifiers

Components

HAL provides hypertext capabilities via two elements:

  1. Resources

    For expressing the embedded nature of a given part of the representation.

  2. Links

    For expressing 'outbound' hyperlinks to other, related resources.

Shared Attributes

The Resource and Link elements share the following attributes:

Note: the following attributes have corresponding target attributes' as defined in Web Linking (RFC 5988)

Link Attributes

The following are attribute definitions applicable only to HAL's Link element.

Resource Attributes

The following are attribute definitions applicable only to HAL's Resource element.

Constraints

The root of a HAL representation MUST be a Resource that links itself to the URI of the resource being represented.

HAL in JSON (application/hal+json)

Note: click the following for a more accessible explanation of HAL in JSON

Further details on the JSON variant of HAL:

Minimum Valid Representation

JSON

{ "_links": { "self": { "href": "http://example.com/" } } }

XML

<resource href="http://example.com/" />

Recommendations

Using URIs for Link relation values

Link relation values used in HAL representations SHOULD be URIs which, when dereferenced, provide relevant details. This helps to improve the discoverability of your application.

For XML, the CURIE syntax MAY be used for brevity.

For JSON, a 'curie' link can be used like so:

{ ... '_links' : { 'curie': { 'href' : 'http://example.com/rels/{relation}', 'name': 'ex' }, ... }, ... }

Acknowledgements

Thanks to Darrel Miller and Mike Amundsen for their invaluable feedback.

Notes/todo