This extension provides documentation on how to filter based on relationships.
Given a requested resource (resource
from now on) that contains several relationships (rel1
, rel2
, … from now on), you can apply filters on the resource
based on conditions on rel1
, rel2
, … The default behavior is to filter the elements on resource
, unless otherwise is specified.
The following request returns only the resource entities that contain a relationship that meets the filter:
GET /resource?filter[rel1.conditionField][value]=value1
- or -
GET /resource?filter[rel1.conditionField]=value1
In the example above conditionField
is a field that exists in the rel1
resource. Only the resource
entities that contain at least one rel1
entity with conditionField
having value1
SHOULD be returned. Every resource
entity returned will contain all of its rel1
entities, regardless of their conditionField
value.
To alter the default behavior, the user can provide the target of the filter. The target can be the resource containing the condition field, or any of its parents until the –top level– resource
.
The following request returns all of the resource
entities, compounding only the ones that meet the filter:
GET /resource?filter[rel1.conditionField][value]=value1&filter[rel1.conditionField][target]=rel1
In the example above, all resource
entities are returned. Each resource
entity will only contain the rel1
entities with conditionField
having value1
.
For a filter on the filter rel1.relA.relAlpha.rel.conditionField
the allowed targets are: rel1
, rel1.relA
, rel1.relA.relAlpha
, and rel1.relA.relAlpha.rel
. The target resource, is the one whose items may be filtered out.
e0ipso/relational-filters
See the extension spec for more information about extensions.
The allowed targets here suggest that relationship names must be unique across the relationship chain. I would suggest that we continue to follow the dot-notation for target values to avoid the following ambiguity:
A collection that promotes a season and a set of selected episodes; it would have a direct relationships with a season and episodes (the episodes won't necessarily be of the same season, but could be all the episodes that highlight a particular character's development):
Collections → season
Collections → episodes
While that episode could also has a relationship to it's season:
Episodes → season
The
season
target in this case is ambiguous for either of these relationships:Collections → episodes → season
Collections → season