Filtering and sorting in API
API list actions support filters and sort order parameters. Available filtering attributes are dependent on the used resource.
Filtering
Filter parameters are prefixed with q..
Each filter parameter is presented as:
q.object_name.attribute.comparator
Example:
/admin/api/elements?q.element.path.$eq=superman&?q.page.id=1
Comparators
General comparators
$eq- matches values that are equal to a specified value (default comparator).$not_eq- matches all values that are not equal to a specified value.
Comparators for number attributes
$gt- matches values that are greater than a specified value.$gteq- matches values that are greater than or equal to a specified value.$lt- matches values that are less than a specified value.$lteq- Matches values that are less than or equal to a specified value.
Comparators for string attributes
$cont- matches (string) values where a field contains a given value.$not_cont- matches (string) values where a field does not contain a given value.$starts- matches (string) values where a field begins with a given value.$not_starts- matches (string) values where a field does not begin with a given value.$end- matches (string) values where a field ends with a given value.$not_end- matches (string) values where a field does not end with a given value.$matches- matches (string) values where a field contains a given value and where*represents any character (e.q.blog*,My * page).$does_not_matchmatches (string) values where a field does not contain a given value and where*represents any character (e.q.blog*,My * page).
Multi match comparators
$in- matches any of the values specified in an array (values should be separated by comma - e.q.page,blog).$not_in- matches none of the values specified in an array (values should be separated by comma - e.q.page,blog).
When dealing with multiple values (arrays) these representations are equal:
?q.element.path.$in=steve-jobs,bill-gates
?q.element.path.$eq[]=steve-jobs&q.element.path.$eq[]=bill-gates
Query values
Using dates and times
Expected format for dates is YYYY-MM-DD e.g. 2015-03-30.
Specified date time should be in ISO8601 format e.g. 2015-03-30T06:48:23Z or 2015-03-30T09:48:23+03:00.
Note: When time column is filtered by using date value then UTC is assumed. E.g. ?q.element.updated_at.$gt=2015-03-30 is same as ?q.element.updated_at.$gt=2015-03-30T00:00:00Z.
Null values
Values null and nil are used to present null value (e.g. /admin/api/elements?q.page.id=null).
Sorting in API
API allows sorting by using parameter s.
Each sorting parameter is presented as:
object_name.attribute.direction
Example:
/admin/api/elements?s=page.id.$asc,element.position.$desc
Sorting directions
Default order direction is $asc (accepted values are $asc and $desc). These representations are equal:
s=element.position
s=element.position.$asc
Sorting by more than one attribute
Ordering by more than one attribute is allowed. Attributes separator is comma (,):
/admin/api/elements?s=page.title,element.position