This extension was developed as part of the jsonapi module for Drupal.
The JSON API specification is agnostic about how a server implements filtering strategies. In fact, the spec says:
Note: JSON API is agnostic about the strategies supported by a server. The
filterquery parameter can be used as the basis for any number of filtering strategies.
This specification covers the gap by specifying an strategy that can be adopted by any JSON API server. This specification will cover:
- Filter conditions: These are the assertions made against the data store which qualify a record for inclusion in a collection result.
- Filter groups.: These allow the creation of complex, nested queries. For example, queries with AND operators within a higher level OR condition.
Filter conditions are represented by conditional objects. These object codify a conditional statement that a JSON API server will execute in order to retrieve a subset of eligible records. These are called where clauses in many data query languages, like SQL.
A conditional object MUST have an arbitrary ID which uniquely idenfies the conditional object inside of the
filter parameter of a JSON API request URI. Additionally, a conditional object MUST contain the following keys:
path. The path property MUST adhere to the property accessor format. The
pathidentifies the property within the entity type that hosts it. The path selects the data value against which the conditional object will be applied. A path MUST be able to select any attribute property of an entity. A path MAY be able to traverse relationships.
value. The value used in the comparison made against the data value of the property identified by the
A conditional object MAY also contain the following keys:
operator. The operator used during the comparison. If nothing is specified, then the operator defaults to
'='. A JSON API server SHOULD implement, at least, the following operators:
<>. In addition to those operators, a server MAY support
IS NOT NULL.
memberOf. If the conditional object should be grouped within a parent group object, this should be that group object's arbitrary ID. If the contents of the
memberOfproperty does not match any group definition ID, then the conditional object MAY be ignored. If this property is not provided, then the current condition SHOULD be assigned to the implicit root group.
In conditionals with operators that act on multiple values (like
value property MUST hold an array of values.
The keys for a filter conditional MUST be wrapped in a
condition property to specify that the arbitrary ID is for a condition.
Property Accessor Format
A property accessor is used to identify a property or sub-property in the requested entity type, or, if the server supports it, any entity type accessible via relationships from the requested entity type. Property accessors MUST contain be a dot separated list of path elements. Each path element MUST be an attribute field or the name of a property in an attribute. If the JSON API server support conditions which traverse relationship, the property accessor MAY contain relationship names as path elements. The last path element of the property accessor MUST be an attribute followed by an optional group attribute's property names.
In the simplest form, the property accessor is just the name of the attribute. For example, the propery accessor for the title attribute of a
blog entity would simply be:
In a more complex form, you may wish to filter based on attributes accessed across a relationship. For example, you wish to get all post created by authors whose accounts were created within the last week. There exists an entity type,
blog, and an entity type
blog type has a relationship to its creating user under the
author relationship. The
user entity type has an attribute of
created representing the date that the user account was established. Thus, the property accessor is simply:
You want to get all TV shows, that contain a published video in a given streaming platform ("netflix"). Assume that there is an object attribute inside of the
/videos resource that contains a list of streaming platforms as keys with a boolean as values.
In this case, the property accessor would be:
videos are relationships,
published is an attribute in the videos entity type and
netflix is a property inside of the
prop inside of the attribute
attr, belonging to the entity type
C wants to be used to include/exclude records in the resource
A. Then there must be a relationship, or a chain of relationships, between entity type
C. In this example, assume that there is a relationship
relAtoB that goes from
B, and relationship
relBtoC that goes from
C. In this scenario the property accessor will be:
A group objecst are used to evaluate multiple conditions or other groups in tandem. They provide the ability to specify a conjunction between multiple conditional objects and/or group objects.
A group object MUST have an arbitrary ID that uniquely idenfies the group object inside of the
filter parameter in the JSON API request URI. Additionally a group object MUST contain the following keys:
conjunction. A JSON API server MUST support
OR. A server MAY support any of:
XNORand other binary logical operators.
memberOf. The result of a group might need to be evaluated inside of a group with other groups and/or conditions. To specify the group this current group belongs to, the
memberOfkey MUST be used.
If no group is specified, a JSON API server MUST assume that all the conditional objects belong to a single implicit root group.
The keys for a filter conditional MUST be wrapped in a
group property to specify that the arbitrary ID is for a group.
Implicit Root Group
Filter and group objects may omit the
memberOf keys. In this case, a server MUST assume that these objects belong to an implicit root group. The JSON API MUST use the
AND conjuntion for this root group.
You want to get all TV shows, that contain a published video in "netflix" or in "hulu". The equivalent filter object shuold be:
orGroup. A group with the or conjunction for the two conditions.
hasNetflix. A condition for the netflix published flag.
hasHulu. A condition for the hulu published flag.
tags. A condition for the tags on the TV show seasons.
That translates to:
filter: orGroup: group: conjunction: OR hasNetflix: condition: path: seasons.videos.published.netflix value: true memberOf: orGroup hasHulu: condition: path: seasons.videos.published.hulu value: true memberOf: orGroup tags: condition: path: seasons.tags value: - awesome - great operator: IN
filter object according to RFC 3986, results in a request like:
GET /api/shows?filter[orGroup][group][conjunction]=OR&filter[hasNetflix][condition][path]=seasons.videos.published.netflix&filter[hasNetflix][condition][value]=1&filter[hasNetflix][condition][memberOf]=orGroup&filter[hasHulu][condition][path]=seasons.videos.published.hulu&filter[hasHulu][condition][value]=1&filter[hasHulu][condition][memberOf]=orGroup&filter[tags][condition][path]=seasons.tags&filter[tags][condition][value]=awesome&filter[tags][condition][value]=great&filter[tags][condition][operator]=IN HTTP/1.1 Host: example.com Content-Type: application/vnd.api+json; ext=fancyfilters Accept: application/vnd.api+json; ext=fancyfilters