HAL
The Hypertext Application Language
application/hal+json (HAL) MUST be used as the representation format of a resource.HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API.
The HAL format is strictly coupled to HATEOAS. The main target of HATEOAS is to decouple the API Consumer from the paths used in the API. The API Client uses the links generated by our API instead of building them from the documentation. This is less error-prone for the API Consumer and it can allow making changes in the API without affecting the API Consumer code.
This document is an informal introduction to the HAL media type. For more details see HAL - Hypertext Application Language Specification.
IANA created a list explaining the standard relationships for REST. Do not forget to have a look here to find the role of each type of relation.
YAML code snippets are provided for OpenAPI Specification 2.0/Swagger and OpenAPI Specification 3.x.
The simplest Hal document looks like an empty JSON (it is an empty JSON!):
{
}
A document representing a "Greeting" resource might look like:
{
"message": "Hello World!",
"_links": {
"self": {
"href": "/greeting"
}
}
}
The field
_links has a special meaning in HAL. It denotes a list of link relations - a pair of a relation identifier and a link (URI).These link relations are used to express the relation of a resource with other resources.
In our case the "Greeting" resource isn't related to other resources but itself, hence the
self relation pointing to the Greeting resource.NOTE: It is customary for every resource representation to include theselflink relation.NOTE: The href MUST always be relative path to the API root (e.g. without the host and scheme).
A more complex document example could be an "Order" resource that has a related resource "Author" (a person who created the order. It might look like:
{
"_links": {
"self": {
"href": "/orders/1234"
},
"author": {
"href": "/users/john"
}
},
"orderNumber": 1234,
"itemCount": 42,
"status": "pending"
}
Let's assume there is an "Orders" resource which is a collection of all orders from different authors. There is the relation between the Orders resource and possibly many Order resources.
We could express this in the
_links object using the order relation, but sometimes it is practical to "embed" (entirely or partially) related resources representations in the originating resource representation. For a scenario like this HAL offers the _embedded field.The
_embedded field's object just contains the related resources HAL representations:{
"_links": {
"self": { "href": "/orders" }
},
"_embedded": {
"order": [
{
"_links": {
"self": { "href": "/orders/1" }
},
"orderNumber": "1",
"status": "pending"
},
{
"_links": {
"self": { "href": "/orders/2" }
},
"orderNumber": "2",
"status": "cancelled"
}
]
}
}
It is important to understand that embedded resource representation might be only partial and might also contain their own embedded resources.
The embedded resource representation should be used as a convenience function (e.g. to reduce the initial number of calls needed at application launch).
Where a full and up-to-date representation of a resource is needed the link relation should exercise the affordance (e.g.
GET /orders/2).Some APIs using HAL:
Spring framework supports HAL out of the box. More info can be found in Spring Documentation and examples.
Last modified 1yr ago