Inclusion of related resources for heterogeneous collections

[jelhan]

The JSON:API specification supports heterogeneous collections containing resources of different types. This is one of the main benefits of requiring a type member for any resource object rather than trying to derive the type from the context. But the support for heterogeneous collections is limited for inclusion of related resources.

A client can request inclusion of related resources using the include query parameter. The client specifies which related resources to include using relationship paths:

The value of the include parameter MUST be a comma-separated (U+002C COMMA, “,”) list of relationship paths. A relationship path is a dot-separated (U+002E FULL-STOP, “.”) list of relationship names.

Problem

This implicitly assumes that all resources in a collection share the same relationship. This may not be true for heterogeneous relationships. The specification leaves it up to the server how to process include requests if the relationship only exists for some resource types in the heterogeneous collection. This problem has been discussed in #1546.

Similar a heterogeneous collection may include resource types having relationships with the same name but different meaning. A client may only want to include the related resources for one type but not the other. Even if both relationships share the same name. Doing so is not supported today.

Solution

I propose adding the possibility to request inclusion of relationship for specific resource types. A client could request inclusion of a relationship for a specific resource type by prefixing the relationship name with a resource type. A colon (:) would be used as a separator between resource type and relationship name.

Examples

Let me illustrate the proposal with some examples:

• GET /projects?include=contributors: Get all projects with their contributors (as today)
• GET /projects?include=internalProject:contributors: Get all projects and include the contributors for internal projects
• GET /projects?include=internalProjects:contributor.manager: Get all projects and include the contributors with their manager for internal projects
• GET /projects?include=internalProjects:contributor.employee:manager: Get all projects and include the contributors. If the contributor is an employee, include the manager of the contributor as well.
• GET /projects?include=internalProjects:contributor.employee:manager, internalProjects:contributor.contractor:company: Get all projects and include the contributors for internal projects. If the contributor is an employee, include the manager of the contributor as well. If the contributor is a contractor, include the company of the contractor instead.

Using colon as a separator

Colon is a reserved character for member names. Using it as a separator does not risk collisions with existing implementations.

Colon is already used as a separator between an extension's namespace and a member name defined by that extension. Scoping an include path to a resource types seems to be similar to namespacing a member to an extension. Using the same character helps consumers to build a mental model.

Drawbacks

This increases complexity of the specification for solving a problem only relevant for a small subset of use cases. Nevertheless I think fixing this gap and ensuring that the spec is cohesive outweighs this trade-off.

It does not solve all issues related to heterogeneous collections. Sorting also assumes that all resources in the collection share the attribute used for sorting. But I think that's a correct required. Sorting cannot be well defined if a sorting criteria can only be applied to a subset of all resources. I think that requirement only needs to be stated more explicitly.