Introduction to Hypertext Application Language (HAL)

Principles of REST architectural style were put forth by Dr. Roy Fielding in his thesis “Architectural Styles and the Design of Network-based Software Architectures”. One of the main principles of the style is that REST applications should be hypermedia driven, that is the change of an application's state or, in other words, transition from one resource to another, should be done by following the links. The rationale behind this principle is that all possible operations with the resource can be discovered without the need of any out-of-band documentation and if some URI changes, there is no need to change the client as it is server's responsibility to generate URIs and insert them into representations. This principle is also called Hypermedia As The Engine Of An Application state (HATEOAS).

While the Thesis gives the prescription to use hyperlinks in the representations of resources, Hypertext Application Language (HAL) is one possible recipe how to do design representations with links. In particular, it describes how to design JSON representations, although there is a XML counterpart too. Our discussion will be limited only to the JSON variety.

As to to HAL media type, currently, according to the document, its media type is application/vnd.hal+json. It has something to do with the fact that there are several registration trees, that is buckets for media types, with different requirements. Examples include standards, vendor and personal trees. The standards tree has no prefix for a media type. The latter two do have vnd and prs respectively. When HAL moves to standards tree, its content type name will be application/hal+json. Currently, the example application provided by the author of HAL, Mike Kelly, produces application/json in its Content-Type header, so the exact media type is not that important for our discussion.

There is a convenient way to tell whether an API is RESTful or not. A so-called Richardson Maturity Model (RMM) was introduced by Leonard Richardson in his 2008 QCon talk and later popularized by Martin Fowler. The model introduces four levels of API maturity starting from Level 0, so that at level two each resource is not only identified by its own URI, but all operations with resources are done using HTTP methods like GET, PUT etc. If an API is at Level 3 it can be considered as RESTful. From the point of view of the RMM HAL helps to upgrade a Level 2 API to Level 3 whereby hypermedia is used.

To make our hands dirty with HAL let's discuss a simple book catalog API where a user can browse books; this API could be a part of a larger application like a bookstore, but its mission only to be a catalog of books. The data for our API could be scraped from amazon.com. Some URIs and methods are listed below.

Let's start with the representation of a single book. A book has certain properties such as the title, the price, number of pages, language and so on. The simplest JSON representation of a book could be like the following.As we deal with representations, the methods to update or modify resources were omitted, although they could be the part of the administrative interface of the service.s

{
    "Title":"RESTful Web APIs",
    "Price":"$31.92",
    "Paperback":"408 pages",
    "Language":"English"
}

It is high time to add some links. The first candidate is a link to the object itself, as it is recommended by the HAL specification. To add links there is a reserved keyword in HAL, _links. The first character of it is an underscore which was selected to make the reserved keywords different from the names of the properties of objects in representations, although not all names starting with an underscore are reserved. Actually, _links is the name of an object the properties of which describe the meaning of a particular link. The values of the properties should contain the URI as well as may contain some other goodies.

Are the names of the properties fixed? Well, some are, and the list is here, but one can add her own as will be described later. Going back to our self link there is an eponymous relation type in the list and our book object can look like the snippet below.

{
    "_links":{
        "self":{
            "href":"/book/123"
        }
    },
    "Title":"RESTful Web APIs",
    "Price":"$31.92",
    "Paperback":"408 pages",
    "Language":"English"
}

The href property contains the URI by following which our resource can be accessed. That is nice, but most books should have authors. While it is possible to add an array of authors' names to our representation, it is more convenient to add links to authors due to the fact that somebody could wish to navigate to the representation of the author's resource and discover what other books a particular author could have written. While there is an author relation type, there is no keyword for the case when there are several authors, so we can add a relation type for this particular case.

Although the relation type could be registered in IANA for public usage to be added to the list, it is important to know how to add one's own rel types. A common practice to do the job is to use a URI by navigating which a description of the relation type could be accessed. The description may contain possible actions, supported representation formats and the purpose of the resource. The first stab at adding authors to our book could look like this.

{
    "_links":{
        "self":{
            "href":"/book/123"
        },
        "http://booklistapi.com/rels/authors":[
            {
                "href":"/author/4554",
                "title":"Leonard Richardson"
            },
            {
                "href":"/author/5758",
                "title":"Mike Amundsen"
            },
            {
                "href":"/author/6853",
                "title":"Sam Ruby"
            }
        ]
    },
    "Title":"RESTful Web APIs",
    "Price":"$31.92",
    "Paperback":"408 pages",
    "Language":"English"
}

By navigating to http://booklistapi.com/rels/authors one can read additional information about this relation type. As it is seen from the snippet above, the properties of a link object are not limited to href, which is the only required one, there are several more properties including title, a human-readable identifier. Some other examples are type for media type and hreflang to hint about the language of the representation. One more notice concerning custom relations is that in its form used above it seems a little bit wordy. HAL has a way to cope with this concern and it is called Compact URI or CURIE.

HAL adds to relation types its own type called curies, example usage of which is demonstrated by the following snippet.

{
    "_links":{
        "self":{
            "href":"/book/123"
        },
        "curries":[
            {
                "name":"ns",
                "href":"http://booklistapi.com/rels/{rel}",
                "templated":true
            }
        ],
        "ns:authors":[
            {
                "href":"/author/4554",
                "title":"Leonard Richardson"
            },
            {
                "href":"/author/5758",
                "title":"Mike Amundsen"
            },
            {
                "href":"/author/6853",
                "title":"Sam Ruby"
            }
        ]
    },
    "Title":"RESTful Web APIs",
    "Price":"$31.92",
    "Paperback":"408 pages",
    "Language":"English"
}

We used the name property of the link object to provide a key to select an object, which is later used in the name of our custom relation type - ns:authors. Then, we used a templated URI which can be expanded to produce the full URI, same as in the previous example, to access documentation. One additional property is templated, which is false by default but should be set to true when using URI templates. Another place where templates can be used are links that enable search whereby search terms are added to the template to produce the full URI.

How this representation can be further improved? Links in a representation could not only be used to add related data, but also to show what possible actions could be taken by the client. For example, if it is an administrative interface, links to edit or delete the book using eponymous relation types may be added. Otherwise, one can add links by following which the client may be able to add a review or rate the book.

We have spent enough time with our book and now let's turn to authors. The example above shows that HAL representation may contain the properties of an object as well as some links. Links can help navigate to related objects, such as authors in our book example. Another way to add information about related objects to our representation is to embed some objects in our representation. For example, if one navigates to the representation of an author, a list of all books with some detail is shown.

{
    "_links":{
        "self":{
            "href":"/author/4554"
        },
        "curries":[
            {
                "name":"ns",
                "href":"http://booklistapi.com/rels/{rel}",
                "templated":true
            }
        ]
    },
    "_embedded":{
        "ns:books":[
            {
                "_links":{
                    "self":{
                        "href":"/books/123"
                    }
                },
                "Title":"RESTful Web APIs",
                "Price":"$31.92"
            },
            {
                "_links":{
                    "self":{
                        "href":"/books/366"
                    }
                },
                "Title":"RESTful Web Services",
                "Price":"$79.78"
            },
            {
                "_links":{
                    "self":{
                        "href":"/books/865"
                    }
                },
                "Title":"Ruby Cookbook",
                "Price":"$34.35"
            }
        ]
    }
}

Another keyword starting with an underscore, _embedded, is used to add data from another object to our representation. Embedded resources are the values of properties which are relation types. The difference from links is that instead of link objects resource objects are used as values. Each embedded object can have properties, links and its own embedded objects, although the latter option is not shown by the example above. The idea is that each representation can contain the trio, including embedded objects, so one has a repeating pattern in nested objects at all levels.

Up to this moment we have dealt only with small lists which may not overwhelm a client if transmitted. A representation of the resource which is a list of books could be extremely demanding from the point of view of network bandwidth and memory consumption on the client side, so it may require pagination. For example, if we deal with the resource which is the list of all possible books, one can include some predefined amount of books along with links which enable the client to transition to the next and previous pages using next and previous relation types respectively.

It should be noted that a representation can contain a link to some resource along with the same resource being embedded and both share the same relation type. This is done to reduce the number of trips to the server and client can extract the necessary information from representation by using relation type.

We have just scratched the surface in learning HAL which is an invaluable tool in designing representations. By reading its specification  and pocking around in the example application one can gain full grasp of the format. Two final notes: first, representations can be validated against schema using some on-line tool; second, list of libraries for working with HAL using various programming languages is here.

References

1. JSON Linking with HAL

2. HAL – Hypertext Application Language

3. JSON Hypertext Application Language

4. An Interview with HAL Creator Mike Kelly