The APIs of Bosch IoT Manager provide several methods for listing devices and gateways. Within those methods, you may add a non-mandatory filter, while setting options to sort and indicate how the list or page of results should look like.This can be done both via the REST API and the JAVA API of Bosch IoT Manager.

Options оverview
- Sorting Operations
- Paging оperations
Using the REST API
- Page iteration
Using the Java API
- Special handling with pageSize argument

Options оverview

Sorting Operations

The sorting operations provide a convenient way to arrange the list of retrieved devices or gateways. The sorting option should follow the pattern:

sort([+|-]{property})
sort([+|-]{property},[+|-]{property},...)

where + is used for an ascending sort order and - for a descending sort order.

For example, this is how to sort the list by the location attribute in ascending order:

sort(+attributes/location)

See Using sorting fields via REST API for more detailed information on the appropriate fields that can be used for sorting criteria and the necessary prerequisites.

Paging оperations

The paging operations allow you to set the desired page size of the response.

The default page size is 25, meaning if no size is explicitly provided, the first 25 results are returned.
The maximum allowed page size is 200.

This paging option should follow the pattern:

size({page-size})

For example, this is how to split the results in pages of 10 devices or gateways:

size(10)

Using the REST API

Filtering of the returned list of results is available with all methods for retrieving devices and gateways. The aforementioned sorting and paging operations are to be defined in the option parameter field, but let us observe the GET /di/devices call and go through all available filtering options:

Filter
The Filter parameter is a query used to filter devices based on their state. See the filter and logical operations that are supported in our REST API documentation.
Namespace
Using the namespace parameter, will return devices and gateways only part of the specified namespace.
Option
The Option parameter allows us to use the valuable sorting and paging operations described above. See 'Adding a cursor' below when retrieving results in pages.
Fields
The Fields parameter determines what should the returned JSON object include as data, e.g. IDs, features, attributes or policyID.

Page iteration

When Iterating over pages, you need to include a cursor as part of the option parameter. The cursor marks the position after the last entry of the previous search. This will iterate the pages and the next call will continue from the entry after the cursor.

The cursor option is:

cursor({cursor-id})

Obtain the cursor from a previous call response and use it as a pointer to the next page. When no more devices/gateways are left, the response will include no cursor.

For example, this is how to start the new page from the position of the cursor LOREMIPSUM:

cursor(LOREMIPSUM)

More examples are available in the REST API of Bosch IoT Manager.

Using the Java API

Using the Java API allows a bit more versatility when creating a new filter for the retrieved list of devices and gateways. One can easily generate a filter object, involving the same sorting and paging options we mentioned as part of the REST API. Keep in mind, that when using the Java API and methods that return a PageIterator, the page size should be set as a parameter. (See Special handling with pageSize argument for details)

The Filter class provides methods for user convenience, but in addition you can also use the general options method to set all options at once, or set the options one by one, using the option method.

To illustrate the different variants let us see how an identical call looks through all of them:

When using the dedicated methods of the builder:

deviceInventory.devices(
  Filter.newBuilder()
    .sort("+id")
    .size(2)
    .build()
);

When using dedicated methods it is not needed to be aware of the format, as even if the paging option syntax is changed, it will be converted to its correct one. In contrast, when using the REST methods the syntax must be property written.

When using the option method:

deviceInventory.devices(
  Filter.newBuilder()
    .option("size(2)")
    .option("sort(+id)")
    .build()
);

When using the options method to set all options at once:

deviceInventory.devices(
  Filter.newBuilder()
    .options("size(2),sort(+id)")
    .build()
);

Be aware that when setting all options at once you should use the options method instead of option.

Special handling with pageSize argument

Methods that return a PageIterator have a filter argument, but in addition include a pageSize parameter as well. In these cases the page size is taken from the second (pageSize) parameter with priority, whereas the size options in the filter, if any, is skipped.