Page History

...

This property contains one or more sub-properties. Each sub-property name defines a relationship to 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 relationshipsrelations:

{
   "firstName":"James",
   "lastName":"Butt",
   "address":"6649 N Blue Gum St",
   "city":"New Orleans",
   "state":"LA",
   "zip":"70116",
   "county":"Orleans",
   "email":"jbutt@gmail.com",
   "_links":{
      "self":{
         "href":"https://www.examples.org/api/customers/1"
      },
      "collection":{
         "href":"https://www.examples.org/api/customers"
      },
      "openOrders":{
         "href":"https://www.examples.org/api/customers/1/orders?status=Open"
      }
   }
}

In the above resource object, there are three relations defined: self, collection, and openOrders. Each relation then includes an href sub-property with a value to the URI that allows the client to request that resource.

In the HAL specification draft, there SHOULD always be a self relation. This references the current resource object, as per the Web Linking RFC. Other relations can be defined by the server and should be immutable. That is, once a relation name has been defined, clients should assume it will never change. The URI that a relation points to can change in order to maintain the decoupled and client/server independent intent of HATEOAS.