Developers

Filtering and sorting in API

API list actions are supporting filters and sort order parameters. Available filtering attributes are depending on 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_match matches (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