Server-supplied default include and sparse fieldset query parameters in related links

1

We currently have a few quite large collections. In most cases, a client only needs a stripped down version of each resource for the list (e.g. type, id, self-link and an attribute like name). The full data is only required in the detail views. Making own resource types for the stripped version seems overkill (and is not backwards compatible), and client-supplied query parameters require domain knowledge. Instead, we’d like to include this in the related link of the relationship like this:

{
“data”:
{
“type”:“Article”,
“id”: “x”,
“relationships”:
{
“comments”:
{
“links”:
{
“related”:“http://some-server/api/articles/x/comments?include=&fields[Comment]=heading”
}
}
}
}
}

I haven’t found any answer in the spec or in the forum to the following questions:

  1. Is it legal to supply the include parameter in the related link? As the spec already allows the server to return a unknown set of included resources by default, a client should most probably work fine, no matter whether we add this to the link or not. Basically this is just a convenience for our server side implementation.
  2. Is it legal to supply the sparse fieldset parameters in the related link? This seems to be more questionable, as the actual resource content in the response changes, and the spec does not seem to require a client to understand server-supplied query parameters. If a client does not understand this, it might screw up local caches, for example.
  3. If it is legal - is a client required to understand the given sparse fieldset parameters?

Alternatively we could add the “cheap” endpoint href (or alternatively a list of query parameters) inside the related meta data:
“links”:
{
“related”: {“href”:“http://some-server/api/articles/x/comments”, “meta”: {“overview_href”: “http://some-server/api/articles/x/comments?include=&fields[Comment]=heading”}}
}

That way, JSON API 1.0 client code by default fetches the full related resources, but more specific (yet domain-independent) clients can fetch the cheap overview one.

Still, I think that somehow supplying default sparse fieldsets would be great. I’d appreciate any further alternatives :slight_smile: