Several endpoints that return a list of objects have 2 query parameters available to filter the data. These parameters are 'Filters' and 'Sorts' which take a string as an input.
Syntax
- Filters is a comma-delimited list of
Name + Operator + Value
whereName
is the name of the property you are choosing to filter.Operator
is one of the Operators in the below table.Value
is the value to use for filtering. BothName
andValue
can have multiple values making use of OR logic. ForName
this can be done by enclosing them in brackets and using a pipe delimiter, eg. (LikeCount|CommentCount)>10 asks if LikeCount or CommentCount is >10. ForValue
you would only need to use a pipe delimiter, eg. Title@=new|hot will return posts with titles that contain the text "new" or "hot". - Sorts is a comma-delimited list of property names to sort by. In case of multiple properties the priority of the sorting depends on the order of the properties in the query. Adding a - before the name switches to sorting in a descending order. eg. -createdBy.
- Page is the number of the page to return.
- PageSize is the number of items returned per page.
Notes:
- You can have spaces anywhere except within
Name
orOperator
fields. - You can use backslashes to escape special characters and sequences:
- commas: Title@=some\,title makes a match with "some,title"
- pipes: Title@=some\|title makes a match with "some|title"
- null values: Title@=\null will search for items with title equal to "null" (not a missing value, but "null"-string literally)
Apply filtering at the server sideIt is recommended to request only the specific data that is required by using filters available with the endpoints.
Examples for filtering and sorting
Properties | Parameters | What it does |
---|---|---|
?sorts= | LikeCount,CommentCount,-createdBy | Sort by likes, then comments, then in descending order by date created |
&filters= | LikeCount>10, Title@=awesome title | Filter properties to only get ones with more than 10 likes and a title that contains the phrase "awesome title" |
Operators
Operator | Meaning |
---|---|
== | Equals |
!= | Not equals |
> | Greater than |
< | Less than |
>= | Greater than or equal to |
<= | Less than or equal to |
@= | Contains |
*= | Starts with |
*-= | Ends with |
!@= | Does not Contains |
!*= | Does not Starts with |
!*-= | Does not Ends with |
@=* | Case-insensitive string Contains |
*=* | Case-insensitive string Starts with |
*-=* | Case-insensitive string Ends with |
==* | Case-insensitive string Equals |
!=* | Case-insensitive string Not equals |
!@=* | Case-insensitive string does not Contains |
!*=* | Case-insensitive string does not Starts with |