Could links and data persist in compound document's relations?


#1

I’ve read the spec many times and haven’t understood is it possible to have links and data in a relationship of resource object inside of included? Like that:

{
  "data": {
  	...
  },
  "included": [
    {
      "type": "blog-posts",
      "id": "1",
      "attributes": {
        "title": "Lorem"
      },
      "relationships": {
        "comments": {
          "links": {
            "related": "/blog-posts/1/comments"
          },
          "data": [
            {
              "type": "comments",
              "id": "1"
            },
            {
              "type": "comments",
              "id": "2"
            },
            {
              "type": "comments",
              "id": "3"
            }
          ]
        }
      }
    }
  ]
}

Should that work without making a request for comments list, but request any of them separately if it’s needed?


#2

To me it looks almost like you’re attempting to use this as a client cache busting technique to push an update to the client ahead of time for the related resource.

As far as if this is OK, the answer is yes there is an example with comments on an article in the Compound Document section which I believe displays exactly what you are doing.

However, I would urge and caution you to be careful if you’re intending to use this as a cache buster or a pre-fetch mechanism for your client. It is extremely important if you plan to do this type of advanced messaging to only use canonical, and normalized resources in the related URLs, or you will introduce an absolute nightmare of cache management for your consumers.

The advice in this specific example I would give is to avoid the related link of “/blog-post/1/comments” in favor of the much better “/comments?filter[blog-post]=1” as this will result in links which are contextualized and updates to the resource on the client referenced by the canonical URL will not need to be managed.

To be explicitly clear to any future readers, the reason “/comments/?filter[blog-post]=1” is better, is because an individual resource in that collection would expected to be at “/comment/1” which as a canonical URL would be useful to the whole API, whereas “/blog-post/1/comments/1” would have an undefined relationship out of the context of the blog post resource because the path is being used to describe the relationship between “blog-post” and “comment”.