Relation Link Usage

2

Hi. You’re definitely not alone in this question so the documentation should probably be clearer. Here’s the difference in short:

  • The self link in a relationship object is called a relationship url. Relationship urls respond with and accept resource linkage (that is, pointers to other resources) rather than full resources.

  • The related link (called the related resource url) responds with full resource objects. It’s designed primarily for GET, though I think the spec would also allow a POST to it, for example (though I’m not sure how many servers implement this).

So, for example GET /articles/1/comments might be a related link and would return a full collection of comments:

{ 
  "data": [{
    "type": "comments",
    "id": "1",
    "attributes": { /* the actual comment data */ } 
  }, {
    // more comments
  }]
}

By contrast, the relationship url, which might be /articles/1/relationships/comments will just return the pointers (technically called “resource identifier objects”), like so:

{ 
  "data": [{
    "type": "comments",
    "id": "1" 
  }, {
    // more type, id pairs identifying comments
  }]
}

You can definitely POST/PATCH/DELETE new resource identifier objects to the latter URI to update which resources are linked as article 1’s comments. And, as I said above, you may be able to POST to the first (related resource) uri to both add a new resource and link it at the same time, if the server supports that.

5 Likes