How to include primary data resources in relationship endpoint response

1

Hello,

My use case: I have a primary resource, and I want to lazily fetch the resources of one of the primary resource’s data. I don’t want to fetch these related resources one by one, so the relationship endpoint initially makes the most logical sense here (at least to me it does).

Please consider this request/response adapted from the spec documentation for fetching relationships:

Request
GET /articles/1/relationships/tags HTTP/1.1
Accept: application/vnd.api+json
Response
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "self": "/articles/1/relationships/tags",
    "related": "/articles/1/tags"
  },
  "data": [
    { "type": "tags", "id": "2" },
    { "type": "tags", "id": "3" }
  ]
}

In this example, I’d like to include the tag resources in this response as well, but I’m not sure of the appropriate way. I’m familiar with the include query parameter, but I’m not sure what value would be for this parameter when requesting the inclusion of primary data. I know that, according to the spec, the include parameter can be used on the relationship endpoint for including relationships to tags. For example, ?include=author would include the resource representing the author of each tag, if such a relationship exists. I want to include the tags themselves.

For the short term, I will request the parent resource as such

GET /articles/1?include=tags HTTP/1.1
Accept: application/vnd.api+json

but this is not ideal as I’m retrieving article data I don’t need.

I’ve considered options like:

  • ?include=. - dot represents the “root” aka primary data
  • ?include=data - this doesn’t seem appropriate since this is not the name of a relationship, but is an option
  • ?include=, - include params are comma-separated, so a comma could indicate an initial empty value indicating root, but this is kinda weird

I’m not seeing if/where this ability is called out in the spec, so I wanted to get some feedback on how best to implement this.

Thanks!

2

You can make an endpoint to fetch the related resources directly, rather than the relationship itself:

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