Clarification on relationship links for resources which belong to other resources

1

Say I have an Article resource. An Article has many Comment resources.

GET /articles/1
Accept: application/vnd.api+json

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "Clarification on relationship links for resources which belong to other resources"
    },
    "relationships": {
      "comments": {
        "links": {
          "self": "http://example.com/articles/1/relationships/comments",
          "related": "http://example.com/articles/1/comments"
        },
        "data": [
          { "type": "comments", "id": "5" },
          { "type": "comments", "id": "12" }
        ]
      }
    }
  }
}

If I can access a Comment via GET http://example.com/articles/1/comments/5 should that return a relationship for the Article which owns the comment?

GET http://example.com/articles/1/comments/5
Accept: application/vnd.api+json

{
  "data": {
    "type": "comments",
    "id": "5",
    "attributes": {
      "body": "Did you read the spec?"
    },
    "relationships": {
      "article": {
        "links": {
          "self": "http://example.com/articles/1/comments/12/relationships/article",
          "related": "http://example.com/articles/1"
        },
        "data": { "type": "articles", "id": "1" }
      }
    }
  }
}

Also, should relationships.article.links.self be another relationships
endpoint specific for the comment like I included? Or alternatively should there not be a relationships URL in this case?

Sorry if this is obvious but I’m struggling to glean a clear answer to this from the spec.

2

Your example says GET http://example.com/articles/1/comments/5, but the body is wrong. The resource object is not inside a data top-level member and the ID is 12, not 5 like in the URL.

I don’t know if GET http://example.com/articles/1/comments/5 can be valid. I’ll let someone else comment on that.

I’m pretty sure your self link http://example.com/articles/1/comments/12/relationships/article is wrong. It should be http://example.com/comments/12/relationships/article. Your related link is also wrong. It should be http://example.com/comments/12/article.

3

@maark thank you for responding. I fixed the example JSON thanks for pointing that out

I don’t know if GET http://example.com/articles/1/comments/5 can be valid. I’ll let someone else comment on that.

I’d be quite surprised if it is illegal (or even discouraged) in JSON API to have nested routes. Saying that everything is important enough to warrant a top level route seems very presumptuous.

It should be http://example.com/comments/12/relationships/article.

Ok but what if I don’t want comments to be a top level route?

4

Ok, I think I understand your idea better now. But I think I should let someone with more experience answer the question. I’ll stick around because I’m interested in the answer.

My guess is that while the specification doesn’t explicitly prevent you from doing this, it seems to go against the spirit of the specification. Most clients might not be able to handle such cases.

5

The request GET http://example.com/articles/1/comments/5 is probably allowed, but to me, the more interesting question is what the 5 means, is it the ID of the resource, or is it the index of the related document? (in your example that would return a 404, since you only have 2 comments)

In either case I would expect that the relationships from the comment will look like: http://example.com/comments/5/relationships/article, otherwise you could end up with urls like http://example.com/articles/1/comments/5/article/comments/12/article/comments/5/article/comments/12/article (or even bigger if you want).