I had a question on the links that get included when a relation is being loaded with the resource. In the documentation examples, there are two links included for relationships:
“self”: “/parent/:id/relationships/:relation”,
“related”: “/parent/:id/:relation”
I was wondering if someone could shed a little light on the use cases for each one. When would the self link get used over the related link and vice versa ? I read that the “relationships” link can be used to directly manipulate the relation itself. Should relationships only be manipulated on a link like this and not the other? Is there any difference in the responses? Is the related link only for GET requests? Is there any overlap?
I could be over thinking it.
1 Like
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
Hi there,
Rather than raise a new ticket I wanted to resurrect this one with a question about your last example @ethanresnick. The response data for a /xxx/relationships/xxx resource, according to the documentation, must be a Resource Identifier Object which can only contain Type, ID and Meta. But what about Links?
It feels like the data returned isn’t much use without at least a self link for each ID, otherwise how does the consumer know how to access each of those linked resources?
I might be missing the point, but could it be something like:
{
"data": [
{
"type": "comments",
"id": "1",
"links": {
"self": "/some/url/1"
}
},
{
"type": "comments",
"id": "2",
"links": {
"self": "/some/url/2"
}
}
]
}
According to the documentation, the above is not legal, so I might be missing something, but the above seems more useful? If I am mistaken, please inform how a consumer is meant to know how to access each of these resources via hypermedia.
If the consumer wants to access these resources, why is it not dereferencing the related resource URL?
@jlangley is right that the way to do this at the moment is to request the related link, but you’re right @josephmcdermott that havin the target uri within each identitifier object would also be convenient. This has come up before and it’s something we hope to address after extensions are done. There’s an ongoing discussion about it here https://github.com/json-api/json-api/pull/926
I’m creating a new implementation and this is very helpful. Just wanted to make sure it’s still valid and didn’t change with 1.1.?. Also, IMO this should be included on the FAQ page.