Sorting And Filtering

Bitbar Cloud API supports sorting and filtering for a number of fields. For anyone that has used REST APIs before, there will not be anything surprising here.

In the below examples we have in most cases removed the curl command details and present only sort and filtering options. The cloud URL (set as environment variable here below) for Bitbar public cloud is https://cloud.bitbar.com and similarly for Private or On-premise setups. Remember to correctly set it before trying out the commands.

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

Sorting

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 the different sorting options by column (:).

Usage

Sorting of API results can be done by either soring in ascending or descending order as presented below. Like shown later below, sorting is supported on specific fields only.

  • sort=field_a - Sort results in ascending order.
  • sort=field_d - Sort results in descending order.

Sorting by One Field

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

Sorting by Multiple Fields

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

Filtering

Usage

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=type_field_operand_value

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

The type of filtering can be one of the following values.

  • N stands for Number type, eg. 7879, 7883, 7901, 7907, 7919 etc.
  • D stands for Date type in Unix millisecond timestamp format, eg. 1526891270000 for Monday, May 21, 2018 8:27:50 AM GMT.
  • S stands for String type, eg. “John Doe”
  • B stands for Boolean type true or false
  • LN stands for List<Number> type, list of number types
  • LD stands for List<Date> type, list of date types
  • LS stands for List<String> type, list of strings
  • LB stands for List<Boolean> type, list of booleans

Supported Operands

GT
Greater than another number
AFTER
After some date in timestamp format example: d_createTime_after_1407319248189
AFTERORNULL
After a date in timestamp format or null value
LT
Less than another number
BEFORE
Before date in timestamp format in milliseconds Example: d_createTime_before_1407319248189
BEFOREORNULL
Before date in timestamp or null value
ON
On specified date in timestamp format. Example: date 08-08-2014 09:30:30 translates to 1407490230000 in 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
EQ
Two values equal
CONTAINS
Contains in Strings
LIKE
Similarity like
EMPTY
Is field empty field
ISNULL
Value is null
ISNOTNULL
Value is not null
IN
Is in list of values (of number, date, string or boolean type)
INORNULL
In list of values or the null value
NOTIN
Is not in list of values

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 (LN) StringList (LS)
GT (Greater Than) X          
AFTER     X      
AFTERORNULL     X      
LT (Less Than) X          
BEFORE     X      
BEFOREORNULL     X      
ON            
EQ (Equal) X X X X    
CONTAINS            
LIKE            
EMPTY            
ISNULL X X X      
ISNOTNULL   X        
IN         X X
INORNULL         X X

Examples

  • Filtering: offline devices

    curl [...] ${CLOUD_URL}/api/v2/devices?filter=b_online_eq_false
    
  • Filtering: online devices with remote control support

    curl [...] ${CLOUD_URL}/api/v2/devices?filter=b_vncSupported_eq_true;b_online_eq_true # devices online with vncSupported
    
  • Filtering: device has property vncSupported AND is online

    curl [...] ${CLOUD_URL}/api/v2/devices?filter=b_vncSupported_eq_true;b_online_eq_true
    
  • Filtering: test run priority property of 50 OR 60

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