Relationship metadata vs. link metadata

1

The 1.0 spec has the following example for metadata on a relationship’s related link:

"links": {
  "related": {
    "href": "http://example.com/articles/1/comments",
    "meta": {
      "count": 10
    }
  }
}

I would have expected the count to be on the relationship itself, though, not just the related link:

"relationships": {
  "comments": {  
    "links": {
      "related": "http://example.com/articles/1/comments"
    },
    "meta": {
      "count": 10
    }
  }
}

I realize this is just an example to demonstrate that links can be objects and not just strings, and is probably not meant to be a recommendation for where to put a count property. But I want to do exactly that, and I’m wondering if this example came from a real-world use case. Has anyone done something like this?

2

In your suggested case, it is no longer clear what the count refers to in all use cases. Consider there being more links.

In the first example, I would instantly assume that it means that there are 10 comments on the article, as there is meta information available on the related link.

In the second example, if there were more links, it is unclear what the count is referring to.

3

The count refers to the number of comment resources in the collection indicated by the “comments” relationship object. I suppose you could have multiple links to different resources that represent the collection of comments, but the “comments” object is still conceptually one collection with a fixed count of content resources. In particular, the “count” value would equal the size of the array value of a “data” property that would be included in the “comments” object if requested. Which is why I think it should appear at that same level in the document.

4

Consider the case of public or private comments. In your example, if the rel name is ‘public’ and ‘private’ with a total count as you suggest of 12, you would have no indication of how many public comments were related. You could do both ways, but this would be redundant.

1 Like