Page History

...

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 that enables RESTful APIs to return JSON (or XML) * content with hypertext (aka hypermedia) that 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 concept of HATEOAS borrows the concept of hyperlinks in HTML formatted media (via the anchor tag) to provide self-documented state changes. The difference is that HTML defines this as a standard which makes it possible for clients to interpret the hyperlinks automatically. Plain old JSON (as well as XML) does  does not define hypermedia in any way. This means any hypermedia included in a JSON object has no self-interpreted meaning. Clients cannot know the difference between a URI that is part of the data model (e.g., a property called companyWebSite) versus a URI that clients can use to navigate to another resource.

Clients have to be told how to tell the difference between normal text versus hypermedia text for it to be useful.

This is why media types registered with the IANA exist. This provides a standards based mechanism for clients to reference.

 HAL resolves this by defining how clients should 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.