HAL is a media type on top of JSON. It’s a format that aims towards a discoverble API by having resources link to one another. Discoverability is one of the pillars of HATEOAS, a principle behind RESTful APIs.
HAL resources follow a standardized format of linked and embedded data. Links contain URIs of related resources or endpoints — relations — and embedding makes it possible to include a related resource into the requested resource.
By means of links our resources self-document their relations with other resources as well as the operations or actions that can be performed on them.
In its most basic form a link consists of a hyperlink and a relationship discriptor, .i.e. the semantic meaning of the relation — let’s call it name from here on. At minimum every resource contains one special kind of link: the self link. As the name suggests, this contains a URI to the requested resource.
Links to resource collection endpoints come in two forms: as a single link or an array of multiple links:
{
"singleLink": {
"href": "/resources/"
},
"arrayOfLinks": [
{
"href": "/resources/123"
},
{
"href": "/resources/456"
}
]
}
The collection resource is a special kind of resource as it doesn’t contain any data on avarage. You should be aware that collections do not automatically embed their elements, but instead link to them individually. It is the client’s responsibility to explicitly embed the resources.
{
"_links": {
"self" : {
"href": "/networks/fedbca0987654321/timeline/"
},
"messages": [
{
"href": "/networks/fedbca0987654321/messages/0123456789abcdef/"
},
{
"href": "/networks/fedbca0987654321/messages/123456789abcdef0/"
},
{
"href": "/networks/fedbca0987654321/messages/23456789abcdef01/"
}
]
}
}
/Related resources can be included in the requested resource. This is called embedding. By default our resources never contain embedded resources, but instead the Speakap API let’s the client decide what it wants to have embedded. The URI query component can be used to instruct the API to embed certain resources.
Important
Only related resources can be embedded. In other words, only the resources for which a link exists.
To embed a linked resource simply specify the name of the relation as the value of the embed
field and add it to the query string of the URL you are requesting.
You can nest embeds by specifying relations of relations using a dot as separator. With nested resources you only have to embed the innermost resource. It is implied that parent resources also need embedding.