REST hypermedia/links to collections

Question

Part of REST best practice is to make use of links in the responses to allow clients to navigate from one entity to another.

For example if I had a customer object type which has child account. If I was to request a customer using /customers/1 then I might provide the following response

{
  "self": "http://localhost:43002/rest/v1/customers/1",
  "id": 1,
  "name": "Isabella Button",
  "number": "000001",
  "forename": "Isabella",
  "surname": "Button",
  "accounts": [
    {
      "self": "http://localhost:43002/rest/v1/accounts/1",
      "id": 1,
      "name": "Main Account",
      "number": "000001",
      "currency": "GBP",
      "fromDate": "2013-01-01",
      "toDate": "9999-01-01",
      "createdDttm": "2013-01-01T00:00:00.000"
    }
  ]
}

Note the self property holds the links.

However let's say I didn't want to return the accounts in the customer query, perhaps the number of accounts might be very large so I don't want to return them by default.

{
  "self": "http://localhost:43002/rest/v1/customers/1",
  "id": 1,
  "name": "Isabella Button",
  "number": "000001",
  "forename": "Isabella",
  "surname": "Button"
}

A resource URL for a customer's accounts could be /customers/1/accounts

However with the customer response above the client would be unable to discover the /customers/1/accounts link.

Is there a best practice for providing hyperlinks in a response that point to "child" collections of the returned resource?

score 5 · Answer 1 · answered Apr 28 '13 at 20:39

5

One practice is to use a links element like this:

{
  "self": "http://localhost:43002/rest/v1/customers/1",
  "id": 1,
  "name": "Isabella Button",
  "number": "000001",
  "forename": "Isabella",
  "surname": "Button",
  "links" : [
     {
       "rel" : "http://www.yourapi.com/rels/accounts",
       "href" : "http://localhost:43002/rest/v1/customers/1/accounts"
     },
     {
       "rel" : "http://www.yourapi.com/rels/someOtherCollection",
       "href" : "http://localhost:43002/rest/v1/customers/1/someOtherCollection",
      }
     ]
}

Or, if you find easier to construct/read the response, you can put the same links as Link http headers.

answered Apr 28 '13 at 20:39

dcernahoschi

14,968
5
37
59

1

this answer is better than mine because in this example the rel-value is provided which makes it more resty ;-), why? => http://avalanche123.com/blog/2011/10/08/about-rel-attribute-from-a-web-developers-point-of-view/, http://blog.steveklabnik.com/posts/2011-12-20-write-better-cukes-with-the-rel-attribute – cproinger Apr 28 '13 at 21:14
@cproinger - Both answers were useful but I preferred yours due to the compactness. A best-practice of providing key/value links under an object was what I was looking for. – Mike Q Apr 28 '13 at 21:44
You're certainly not restricted from providing rel in the links meta object either - avoiding the need for iteration can become important when the amount of links you may need starts to grow – Brian Jun 07 '14 at 13:43

score 2 · Accepted Answer · answered Apr 28 '13 at 20:38

2

provide a links attribute like in this example http://caines.ca/blog/programming/json-is-under-defined-for-rest/

{
 "links": {
   "self" : { "href": "{id}" },
   "up" : { "href": "{upId}" },
   "children" : { "href": "{id}/children" }
 }
}

answered Apr 28 '13 at 20:38

cproinger

2,258
1
17
33

REST hypermedia/links to collections

2 Answers2