Sorting and Filtering
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
Important
For BitBar v. 2.86 and earlier, the filter format is filter=type_field_operand_value, where type is a 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