Hypertext Application Language

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.


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.


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

Name Type Value
embed string Comma-separated list of relations


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

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