HAL versus the swamp of POX

Everyone wants to build good REST APIs, but pure implementations are not always straightforward.  For instance, a standard representation of a resource that includes links to other resources still escapes many.

The Richardson Maturity Model defines a 4-step journey from the “Swamp of POX” (plain old XML) to the “Glory of REST.” The first 2 steps from the swamp are more easily achieved than the final step of “Hypermedia Controls,” often referred to by the clunky acronym HATEOAS (hypertext as the engine of application state). This is because defining resources with URIs (step 1) and using HTTP verbs correctly (step 2) are well covered by standards, and good practices are generally built into to REST frameworks used by developers.

In order to implement HATEOAS, it is necessary to define links between resources so that a client can easily navigate the API without referring to external documentation. But there is no defined standard for how to define the links, particularly in JSON format.

This leaves developers to define their own, which will result in the same problem being solved in different ways in different APIs.  API users could benefit from a standard approach to avoid learning a new approach for each API. This is where HAL (and a similar standard called Siren) can help. HAL (the Hypertext Application Language) claims to be HTML for machines and defines a structure for HATEAOS resources in both JSON and XML formats.

Although HAL is not a standard as yet, there are libraries for building HAL resources for the most popular languages (Java, Python, Ruby and C# to name a few), and support for HAL has been added to Backbone JS by the author of the HAL specification, Mike Kelly.

The need for a standard way of defining HATEOAS resources is real and HAL fits the gap well. API developers will be doing their clients a favour by adopting a standard way of defining resources, even if HAL is yet to be ratified as a W3C standard.