Hypertext Application Language

HAL is a media type on top of JSON. It’s a format that aims towards a discoverable 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.

Links

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 descriptor, .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 average. 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.

Example

{
    "_links": {
        "self" : {
            "href": "/networks/fedbca0987654321/timeline/"
        },
        "messages": [
            {
                "href": "/networks/fedbca0987654321/messages/0123456789abcdef/"
            },
            {
                "href": "/networks/fedbca0987654321/messages/123456789abcdef0/"
            },
            {
                "href": "/networks/fedbca0987654321/messages/23456789abcdef01/"
            }
        ]
    }
}

Conventions

• The URI of a resource endpoint always ends with a forward slash /
• The name of a relation to multiple resources is always plural.
• The name of a relation to a single resources is always singular.

Embedding

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.

CUSTOM-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.

Query Parameters

Syntax

embed = rel path, { ",", rel path } ;
rel path = ? HAL relation ? , { ".", ? HAL relation ? } ;

(* HAL relation = relation name from the links section *)