Filtering

All filtering related query parameters begin with filter.

Filtering using a target

Most list endpoints in spaces are filterable and for every list, every field is also filterable by field name. The most basic example is: filter[$target]=$value. The target would be the field name and value is the value you wish to filter for.

An example might be title and basic usage would look like filter[title]=test. I.e. show me the deals which have a title containing test.

Filtering multiple fields

To filter by multiple fields simply add more filter query params such as filter[title]=test&filter[isHomepage]=true

Operators

Currently Spaces only supports filter[title]=tes which is, by default, a contains operation so will match on test, testers etc. We will be bringing further filtering support as shown below in future

A more advanced version would be filter[$target][$operator]=$value; e.g. filter[title][in]=test,hello. The operator is optional. It defaults to eq but can be any of the following:

Operator Example Description
eq foo Value is equal to
in open,closed Value exists in comma-separated list of values
like *foo* Value is like (uses wildcard). Wildcards at start at end is like “contains”, just at the start would be “ends with”, and just at the end would be “starts with”
gt 2018-02-26T00:00:00Z Value is greater than
gte 1 Value is greater than or equal to
lt 2 Value is less than
lte 3 Value is less than or equal to

Binding

Currently Spaces does not support alias names in filters, but we aim to make this available in future

There can also be an “alias” given to a filter; e.g. filter[$target][$operator][$alias]=$value. The alias is optional and will default to the $target if omitted. Aliases can contain [a-zA-Z0-9-_].

The alias allows the API user to build more complex conditions to filter on. By default every filter provided is put together with AND. What if you wanted “this filter or this other filter”? Or “this or not this other filter”? That’s what filter[binding] is for.

?filter[binding]=$expression

$expression can contain aliases and symbols;

Operator Type Example
& AND a&b
| OR a|b
! NOT !a
() Brackets (a|b)&c

If a binding is given it must contain all provided filters.

Example

First name is “John” or last name is not “Smith”

GET contacts  
?filter[firstName][eq][alias1]=John  
&filter[lastName][randomAliasName]=Smith  
&filter[binding]=alias1|!randomAliasName

Feedback

If you have any feedback or suggestions, feel free to contact us at api@teamwork.com.