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.
@helior, @deviantintegral can you point out the confusing wording? :yoda: 😄