Last modified on October 21, 2020

BitBar Cloud API supports sorting and filtering of response fields.

In this topic, the examples present only sorting and filtering options, and the cURL command details are removed. The cloud URL for BitBar Public Cloud is set as an environment variable:

export CLOUD_URL=https://cloud.bitbar.com/

Remember to correctly set it before trying out the commands.

Sorting

The Bitbar Cloud API supports sorting of the queried results in either ascending or descending order as described below. It is also possible to sort based on multiple criteria and separate different sorting options by column :. Sorting is supported on specific fields only.

sort=field_a

Sorts results in ascending order.

sort=field_d

Sorts results in descending order.

Sort by one field

curl [...] ${CLOUD_URL}/api/v2/devices?sort=displayName_d

Sort by multiple fields

curl [...] ${CLOUD_URL}/api/v2/devices?sort=accountId_d:displayName_a

Filtering

API responses can be filtered to avoid large result sets and retrieving only information that is of interest instead of getting everything, and then filtering through results locally.

filter=field_operand_value

For BitBar v. 2.86 and earlier, the filter format is filter=type_field_operand_value, where type is a type of filtering.

Type of filtering

The API supports multiple filtering options and filtering based on multiple values. For this filter part, the delimiter is _, the argument delimiter is |, and the filter delimiter is ;.

Supported operands

AFTER

Filters the response so it shows the fields with the value which is the next day after the date you specified, in the timestamp format. For example: d_createTime_after_1407319248189.

AFTERORNULL

Filters the response so it shows the fields with the value which is the next day after the date you specified, in the timestamp format, or a null value.

BEFORE

Filters the response so it shows the fields with the value which is the day before the date that you specified, in the timestamp format in milliseconds. For example: d_createTime_before_1407319248189.

BEFOREORNULL

Filters the response so it shows the fields with the value which is the day before the date that you specified, in the timestamp format, or a null value.

CONTAINS

Filters the response so it shows the fields with the specified value.

EMPTY

Filters the response so it shows the fields with empty values.

EQ

Filters the response so it shows the fields with two equal values.

GT

Filters the response so it shows the fields with the value which is greater than the value you specified.

IN

Filters the response so it shows the fields with the value which is in the list of values (of number, date, string, or boolean type).

INORNULL

Filters the response so it shows the fields with the value which is in the list of values or the fields with the null value.

ISNOTNULL

Filters the response so it shows the fields with the value which is not null.

ISNULL

Filters the response so it shows the fields with the null value.

LIKE

Similarity like.

LT

Filters the response so it shows the fields with the value which is less than another value you specified.

NAME_NOTLIKE

Applies to:

Filters the response so it returns items where the value of the specified field does not match the specified value.

NOTIN

Filters the response so it shows the fields with the value which is not in the list of values.

ON

Filters the response so it shows the fields with the specified date in the timestamp format. For example: date 08-08-2014 09:30:30 translates to 1407490230000 in the timestamp millisecond representation. So, d_createTime_on_1407490230000 means finding entities where createTime >= 08-08-2014 00:00:00 and createTime < 09-08-2014 00:00:00.

All filtering options are not available with all operands or value types. The below table describes when and which operands are supported.

Operand/Type Number (N) String (S) Date (D) Boolean (B) Number List (NL) String List (SL)
AFTER
AFTERORNULL
BEFORE
BEFOREORNULL
CONTAINS
EMPTY
EQ
GT
IN
INORNULL
ISNOTNULL
ISNULL
LIKE
LT
NAME_NOTLIKE
ON

Examples

Filter offline devices

curl [...] ${CLOUD_URL}/api/v2/devices?filter=online_eq_false

Filter online devices with remote control support

curl [...] ${CLOUD_URL}/api/v2/devices?filter=vncSupported_eq_true;online_eq_true # devices online with vncSupported

Filtering: a device has property vncSupported and is online

curl [...] ${CLOUD_URL}/api/v2/devices?filter=vncSupported_eq_true;online_eq_true

Filtering: test run priority property of 50 or 60

curl [...] ${CLOUD_URL}/api/v2/devices?filter=priority_in_50|60

See Also

Bitbar REST API

Highlight search results