Filtering, pagination, and sorting

The Control Room API supports filtering, pagination, and sorting for endpoints that return arrays of resources.

The filtering mechanism filters the required resources, the sorting mechanism places the resources in order; and the pagination mechanism then returns a specific range of those ordered resources. This topic provides you the details to filter and sort the results of an API requests and also guides to handle the pagination of large result sets returned from an API request.
Note:
  • Sorting and filtering are supported for substrings. For example, if you want to search for bots or files that have fin in their names, enter fin as the search criterion. All the bots and files that contain fin in the names will be displayed, for example, Finance, Finder, DeltaFinance, and Dolfin.
  • Wildcards are not supported for searching and filtering bots or files.

Filtering

Filtering allows you to apply Boolean condition against a collection of returned resources in order to subset the collection to only those resources for which the condition is true. The most basic operation in an Control Room API filters is to compare a field to a given value. It is possible to use equality comparison, range comparison, or logical . Use the following operators to compare a field to a constant value.
Operation Description Example
Equality comparison
eq Equals UserEmailAddress, eq first.last@aa.com
ne Not Equals UserEmailAddress, ne first.last@aa.com
Range comparison
lt Less than Quantity lt 1500
le Less Than or Equal Quantity le 1500
ge Greater Than or Equal CreatedDateUtc ge 2021-03-15
gt Greater Than CreatedDateUtc gt 2021-03-15
Logical
and And Field1 eq 'abc' and Field2 eq 'def'
or Or Field1 eq 'abc' or Field2 eq 'def'
The filter query parameter allows you to apply basic, multiple, and convention oriented filters to a request. The filters in the Control Room APIs are applied with single parameter or with multiple parameters.

Single parameter filter

Single parameter filter allows the API request to select the responses by matching one or more members of the response to the value passed in the query. The single parameter filter is represented in the following image:
Single Parameter filter

The JSON equivalent of the above image (single parameter filter) looks like:
{
  "filter": {
    "operator": "<NONE, lt, le, eq, ne, ge, gt, substring, and, or, not>",
    "field": "string",
    "value": "string"
  }
}

For example, to list all the device pools that has a substring finance, use the following single parameter filter:

POST http://{{ControlRoomURL}}/v2/devices/pools/list
{
   "filter":{
      "operator":"substring",
      "field":"name",
      "value":"finance"
   }
}

For more detailed sample on a single parameter filter, see Device Pools API .

Multiple parameter filter

Multiple parameter filter allows you to filter the results based on combining multiple conditions wrapped in logical operands and and or.
  • and: A binary operator that evaluates to true if all the conditions in the operands evaluate to true.
    Multiple parameter filter - AND
  • or: A binary operator that evaluates to true if atleast one of the conditions in the operands evaluate to true.
    Multiple parameter filter - OR
The JSON equivalent of the above image (multiple parameter filter) looks like:
{
  "filter": {
    "operator": "<and, or>",
    "operands": [
      {
        "operator": "<NONE, lt, le, eq, ne, ge, gt, substring, and, or, not>",
        "field": "string",
        "value": "string"
      },
      {
        "operator": "<NONE, lt, le, eq, ne, ge, gt, substring, and, or, not>",
        "field": "string",
        "value": "string"
      }
    ]
  }
}

For example, to list all the roles that has a substring Device, createdOn is after 2022-04-01, and createdOn is before 2022-05-31, use the multiple parameter filtering with logical add operator as follows:

POST http://{{ControlRoomURL}}//v1/usermanagement/roles/list
{
   "filter":{
      "operator":"and",
      "operands":[
         {
            "operator":"substring",
            "field":"name",
            "value":"Device"
         },
         {
            "operator":"gt",
            "field":"createdOn",
            "value":"2022-04-01T00:00:00.989Z"
         },
         {
            "operator":"lt",
            "field":"createdOn",
            "value":"2022-05-31T23:00:00.123Z"
         }
      ]
   }
   }

For more detailed sample on a single parameter filter, see User Management API .

Pagination

Pagination allows you to:
  • Retrieve a limited collection of results.
  • Offset a collection of results.
All Control Room APIs that returns a collection of records are paginated. API methods that support pagination takes two (optional) parameters:
Operation Description
offset The offset parameter controls the starting point within the collection of response results. Default value is 0.
length The length parameter is the maximum number of records to retrieve starting from the offset. Default value is 200.
The JSON snippet for pagination looks like:
"page":{ 
    "offset":5,
    "length":10
    }

For more detailed sample on a single parameter filter, see User Management API .

Sorting

Sorting allows you to order the results by any field, in ascending or descending order. For example, if you are returning the roles, you can sort the roles by last modified date.

 "sort": [
    {
      "field": "string",
      "direction": "<asc, desc>"
    }

Direction

Type: Enum [ desc, asc ]

  • asc = ascending (smallest to largest, 0 to 9, A to Z)
  • desc = descending (largest to smallest, 9 to 0, Z to A)

For more detailed sample on a single parameter filter, see User Management API .