You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 27 Next »

No, this is not a reference to the HAL 9000 from Clarke's 2001: A Space Odyssey,

Quick Answer

HAL is an acronym for Hypertext Application Language and is designed to provide "...a set of conventions for expressing hyperlinks in either JSON or XML." HAL is an IANA registered media type. This enables RESTful APIs to return JSON* containing hypertext (aka hypermedia) which can be easily interpreted by machine and human agents. Because it is a registered media type, developers can specify application/hal+json as the value for the Content-Type response header.

* There is a HAL media type for both JSON and XML. However, we will limit our attention to JSON since that is what the SRP HTTP Framework uses by default.

Digging Deeper

In our What is REST? article we introduced an important aspect of the Uniform Interface constraint known as HATEOAS. The intent of HATEOAS borrows the concept of HTML hyperlinks as a means of providing self-documented options to users. The difference is that HTML defines this as a standard which makes it possible for clients to interpret the hyperlinks automatically. Plain old JSON does not include any definition for hypermedia. This means any hypermedia included in a JSON object has no way of being self-interpreting. Clients cannot know the difference between a URI that is part of the static resource data versus a URI that clients can use to navigate to another resource.

HAL resolves this by extending JSON to include hypermedia and define the standard so clients can properly identify hypermedia within JSON objects. This is why the SRP HTTP Framework normally sets the Content-Type response header to application/hal+json instead of just application/json. It is important to note that HAL does not redefine JSON. This means clients can navigate and parse HAL content using the same rules as standard JSON.

Reserved Properties

HAL reserves two properties so that clients can interpret hypermedia in a JSON resource object: _links and _embedded. These properties are prefixed with underscores to avoid collision with properties that developers might use in actual static resource objects.

_links

This property contains one or more sub-properties. Each sub-property name defines a relationship to the primary resource object. The sub-property values are themselves name/value pairs. Here is an example of a resource object containing a few link relationships:

{
   "firstName":"James",
   "lastName":"Butt",
   "address":"6649 N Blue Gum St",
   "city":"New Orleans",
   "state":"LA",
   "zip":"70116",
   "county":"Orleans",
   "email":"jbutt@gmail.com",
   "_links":{
      "self":{
         "href":"https://www.examples.org/api/customers/1"
      },
      "collection":{
         "href":"https://www.examples.org/api/customers"
      },
      "openOrders":{
         "href":"https://www.examples.org/api/customers/1/orders?status=Open"
      }
   }
}
  • No labels