Page History
No, this is not a reference to the HAL 9000 from Clarke's 2001: A Space Odyssey,
Table of Contents
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.
...
HAL reserves two properties so that clients can interpret hypermedia in a 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 its relation 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 relations:
...
HAL intentionally defined link relations to be simple. To support the self-documenting and discoverability intent of a RESTful API, clients should be able to use the OPTIONS HTTP method to get a list of all supported HTTP methods for a given API. The list of all supported HTTP methods is expected to appear in the Allow response header. The SRP HTTP Framework handles this automatically.
_embedded
This property contains one or more sub-properties. Each sub-property name defines one or more embedded resource objects within the current resource object. These embedded resource objects (which are technically sub-resources) represent a partial or whole resource object that should have its own API (i.e., URI endpoint). The reason for including embedded resource objects will vary and are always based on the developer's needs. Embedded resource objects are typically added to provide one API with enough additional resource information to prevent the need for additional API calls. This is very common with collection APIs. For example, in the above resource object we identified a URI with a relation of collection. An inspection of the URI itself reveals that the endpoint is simply /customers. The absence of a unique identifier to a customer (e.g., /customers/1) is expected to mean "all customers", also referred to as "the collection of customers".
...
While HAL is not the only IANA registered media type that provides standards for including hypermedia in JSON objects, it is one of the most popular and easiest to implement. For this reason, the SRP HTTP Framework provides the AddLinkRelationship and AddLinkRelation and AddEmbeddedResources services to make it much easier to create HATEOAS APIs.
