Bosch IoT Device Management

Search HTTP API introduction

Developers can search for Things via the Bosch IoT Things HTTP API. The search criteria can be defined using a filter (RQL). Further, they can define a sort order and the pagination of the search results.

The following operations are available over the HTTP API:

images/confluence/download/attachments/1783513629/things-http-api-2-search.png

The operators provided to compose a search request are described in the following sections.

Search - root resource

The root resource itself is the endpoint for further search operations.
The filter parameter is optional. If omitted, the search will return all Things on which the currently authenticated user has READ permission.

 https://<host>/api/2/search/things?filter=<your-search-criteria>

Example - all things in the living room

 https://<host>/search/things?filter=eq(attributes/location,"living-room") 

Starting with HTTP API v2 the search result is limited to the Things within the namespace (or namespaces) the solution is configured for.
With the namespaces parameter it is possible to search in other known namespaces.

Search - count resource

The search/things/count resource can be used to count things.
The filter parameter is optional. If omitted, the search will return all Things on which the currently authenticated user has read permission.

Example - count the things in the living room

 https://search/things/count?filter=eq(attributes/location,"living-room") 

Search defaults

  • Namespace – if you don’t explicitly request for things of specific namespaces, only the things of the default namespace are listed (respectively of all namespaces of your solution in case you have booked a Standard plan)

  • Filter – if you don’t use the RQL filter, you will get all things

  • Sorting – if you don’t specify any sort criteria, the things will appear in alphabetical order - sorted by their thingId

  • Page size - by default, one page of search result will contain 25 things (max. is 200)

Search restrictions

  • The search is case sensitive.
    In case you don’t know how exactly the spelling of the namespace, name, attribute, feature etc. is, use the like notation for filtering

  • Search on array fields is not supported

  • The internal search index is “eventually consistent”.
    Consistency with the latest thing updates should recover after a while.

  • The search index can hold max. 950 Byte for the path and the value combined.

SearchIndex of namespaces

If a filter is applied to the search request, the fields that are filtered upon have to be included in the SearchIndex of the namespaces set to the request.

If your subscription has multiple namespaces and no namespace is set in the search request, the search will apply to all namespaces. For such a case, the specific fields used in the filter need to be indexed in all namespaces of the corresponding subscription, otherwise you will run into an error. The error message will tell you which namespaces’ index needs to be updated respectively. In case you search in a namespace which belongs to another subscription, please inform the respective owner about which fields you would need as search criteria.

Search - fields

The following fields help you to more precisely describe what you are actually searching for.

  • thingId

  • policyId

  • all feature IDs

  • all feature properties

  • all feature desiredProperties

  • all attributes

  • _namespace

  • _created

  • _modified

  • _policy

  • _revision

The fields can be used in a search filter as well as for sorting the results.