Usage of `related` field in Relationships link

8

Yes, absolutely! Your example, with the top-level "self" link pointing to http://examples.com/bands/1/relationships/drummer while the one at the resource object level (i.e., the one under "data") points to http://example.com/musicians/9, is exactly correct. And it’s a perfect demonstration of why both levels exist.

 

Definitely. The drummer represented is just a standard resource object, so it can certainly include relationships of its own. In fact, it should include those additional relationships if they exist (unless there’s a ?fields restriction). That way, users can just follow one relationship to the next, to the next, without ever having to go back and request /musicians/9 directly.

 

Just a brief aside: JSON API suggests using /bands/1/drummer as the "related" link, to save /bands/1/relationships/drummer for the "drummer" relationship’s "self" link, like so:

GET /bands/1

{
  "data": {
    "type": "bands", 
    "id": "1", 
    "attributes": { /* attributes */},
    "relationships": {
      "drummer": {
        "links": {
          "self": "http://example.com/bands/1/relationships/drummer",
          "related": "http://example.com/bands/1/drummer"  // no "/relationships/" by convention
        }
      },
      // other relationships
    }
  }
}

However, following this recommendation is absolutely not required. If you want to use http://example.com/bands/1/relationships/drummer as the "related" link, and make up something else for the "self" link (or not include one), that’s fine. A conforming client will use whatever strings the "self" and "related" keys hold. Still, following the convention can make your API seem a bit more familiar to developers who have worked with other JSON API backends.

Note: For a discussion of the differences between the "self" and "related" links of a relationship object, since I don’t think it came up in the earlier discussion, see here.

1 Like