Beginning with v4 of the API search patterns have been changed to use a POST on a “/Search” path to allow for Unicode characters as well as deep search for child objects. The header GET filters described below continue to work in v4 to retain backwards compatibility.
Many times you will need to filter and sort your GETs. For example, you might want all the invoices belonging to a specific account ordered by date. To do this you need to use the search request header. Search requests allow you to filter and sort the returned data on one or more properties of the object. The basic forumula for the search request is:
A filter array that can be conceptualized as where clauses.
A condition which logically joins the filter array with the orderby array using a logical AND
An orderBy array that sorts the returned data
Filters
A filter combines a property, an operator, and a value. Since the filter is an array, elements can be combined using the condition property with a value of 'and'.
Filter Property | Definition |
---|---|
name | "name": "accountID" |
operator | "operator": "eq" |
value | "value": 42 |
condition | "condition": "and" |
Here is an example of a basic filter:
{ "filters": [ { "name": "name", "value": "Admin", "operator": "eq" } ] }
Combining Filters
Elements in the filters array are combined using the AND condition and by adding a new element to the array. Building on our previous example, here is an example of filter with two conditions:
{ "filters": [ { "name": "name", "value": "Admin", "operator": "eq", "condition": "and" }, { "name": "currencyId", "operator": "eq", "value": 1 } ] }
Ordering Filters
The orderBy property allows you to sort the response items by ascending or descending values based on one of the properties. Let's add an orderby condition to our example:
{ "filters": [ { "name": "name", "value": "Admin", "operator": "eq", "condition": "and" }, { "name": "currencyId", "operator": "gt", "value": 1 } ], "condition": "and", "orderBy": [ { "name": "created", "direction": "desc" } ] }
Let's combine two orderBy elements and see what our filter looks like:
{ "filters": [ { "name": "name", "value": "Admin", "operator": "eq", "condition": "and" }, { "name": "currencyId", "operator": "eq", "value": 1 } ], "condition": "and", "orderBy": [ { "name": "name", "direction": "asc" } ] }
Making the Request
Let's add the header to our GET request. The resulting JavaScript XHR code snippet:
xhr.open("GET", "https://mydomain.com/ResourceServer/api/v1/Account", true); xhr.setRequestHeader("Accept", "application/json") xhr.setRequestHeader("Content-Type", "application/json"); xhr.setRequestHeader("Authorization", "Bearer " + yourBase64token); xhr.setRequestHeader("SearchRequest", " [\"{\"filters\":[{\"name\":\"name\",\"value\":\"Admin\",\"operator\":\"eq\",\"condition\":\"and\"},{\"name\":\"currencyId\",\"operator\":\"eq\",\"value\":1}],\"condition\":\"and\",\"orderBy\":[{\"name\":\"created\",\"direction\":\"desc\"},{\"name\":\"name\",\"direction\":\"asc\"}]}\"],"); xhr.send();