JSON:API currently lacks a standard for filtering/querying data included through relationships, as opposed to GraphQL which has this firmly specified.
Consider the following API:
GET /authorsto get all resources of type
articleswhich is to-many
Now consider the following request:
- “Give me all authors who have draft articles, and include their draft articles”.
There are two filters here:
- The filter on the author list (filtering on a related resource’s attribute)
- The filter on the included articles
Here is a syntax that might be able to confer the necessary distinction:
GET /authors ?filter[articles.isDraft]=true &filter[articles][isDraft]=true &include=articles
The meaning of the two filters would be:
filter[articles.isDraft]=truemeans "only return authors who have articles with
filter[articles][isDraft]=truemeans "for any included articles from the
articlesrelationship, only return those with
In other words:
- The first (of two) pair of brackets indicate what to filter (if not present, filter top-level data)
- The second (or only) pair of brackets indicate how to filter, using dot notation for filtering on related resources
As far as I can see, this syntax is general enough to be nested artibrarily on any level. For example,
filter[articles.comments][author.name]=John&include=articles.comments means "for each article, include only those comments that have
Does this make sense? Could this syntax be a clear, general, and consistent way to support filters on nested relationships?