Search API v1 - deprecated

An IoT developer can search for Things by simple attribute values via the Bosch IoT Things HTTP API. Further, he can define a sort order and the pagination of the search results.

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/1/search/things?filter=<your-search-criteria>

Example - search for all things in the living room

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

note Things created via API 2 will use Policies (instead of ACL entries) and can thus not be found at API 1. However, the search functionality at API 2 will be able to find Things which have been created via API 1. Find details at updates.

Search count Resource

The search/things/count resource 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://api/1/search/things/count?filter=eq(attributes/location,"living-room") 

The following operations are available over the HTTP API: cr-rest-api-search.png

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

Parameter: filter

This filter parameter defines the search query by aggregation of the following operators.

note Please note that whitespaces are only allowed inside of quoted string values.

For example:

eq(attributes/manufacturer, "ACME")

is not allowed because of the whitespace after the comma, but

eq(attributes/manufacturer,"ACME")

and

eq(attributes/manufacturer,"ACME Holding")

are okay.

Relational operators

eq

 eq(<property>, <value>) = <query> 

(i.e. equal to the given value)

Example - search for things owned by “SID123”

 filter=eq(attributes/manufacturer,"SID123")

ne

 ne(<property>, <value>) = <query> 

(i.e. not equal to the given value)

Example - search for things with manufacturer different than “SID123”, or no manufacturer assignment

 filter=ne(attributes/manufacturer,"SID123")

note When using a negating expression, such as not or ne, (not equal) please keep in mind that you might experience a longer time to get the response. Compared to other search operators we observed longer response times ourselves.

gt

 gt(<property>, <value>) = <query> 

(i.e. greater than to the given value)

Example - search for things with thing ID greater than “A000”

 filter=gt(thingId,"A000")

ge

 ge(<property>, <value>) = <query> 

(i.e. equal to the given value or greater than it)

**Example - search for things with thing ID “A000” or greater **

 filter=ge(thingId,"A000")

lt

 lt(<property>, <value>) = <query> 

(i.e. lower than the given value or equal to it)

Example - search for things with thing ID lower than “A000”

 filter=lt(thingId,"A000")

le

 le(<property>, <value>) = <query> 

(i.e. lower than the given value)

Example - search for things with thing ID “A000” or lower

 filter=le(thingId,"A000")

in

 in(<property>, <value>, <value> , ...) = <query> 

(i.e. contains at least one of the values listed)

Example - search for things with thing ID “A000” or “AB00” or “AZ99”

 filter=in(thingId,"A000","AB00","AZ99")

like

 like(<property>, <value>) = <query> 

(i.e. contains values similar to the expressions listed)

Details concerning the like-operator The like operator provides some regular expression capabilities for pattern matching Strings.
The following expressions are supported:

  • *endswith => match at the end of a specific String.
  • startswith* => match at the beginning of a specific String.
  • *contains* => match if contains a specific String.
  • Th?ng => match for a wildcard character.

Examples

 filter=like(attributes/key1,"*known-chars-at-end")
 filter=like(attributes/key1,"known-chars-at-start*") 
 filter=like(attributes/key1,"*known-chars-in-between*") 
 filter=like(attributes/key1,"just-som?-char?-unkn?wn")

exists

 exists(<property>) = <query> 

(i.e. search for all things in which the given path exists)

Example - search for things which have a Feature with ID “feature_1”

filter=exists(features/feature_1)

Details on Property

 <property> = url-encoded-string

To search for nested properties, we use JSON Pointer notation (RFC-6901 - https://tools.ietf.org/html/rfc6901).

The following example shows how to search for the sub property location of the parent property attributes with a forward slash as separator:

 eq(attributes/location,"kitchen")

Details on Value

 <value> = <number>, <string>, true, false, null
 <number> = double, integer
 <string> = ", url-encoded-string, "

Comparison of string values

note Please note that the comparison of string values is supported by the API, but its behavior is not specified and may change in future releases. This affects the comparison operators gt, ge, lt and le.

Logical operators

and

 and(<query>,<query>, ...) = <query>   

(i.e. all given values match)

Example - search for things which are located on the “upper floor” in the “living-room”

 filter=and(eq(attributes/floor,"upper floor"),eq(attributes/location,"living-room"))  

or

 or(<query>,<query>, ...) = <query>  

(i.e. at least one of the given values match)

Example - search for all things located on the “upper floor”, and all things with location “living-room”

 filter=or(eq(attributes/floor,"upper floor"),eq(attributes/location,"living-room"))

not

not(<query>) = <query>

(i.e. the negation/opposite of the given query)

Example - search for all things with floor different than “upper floor” or without any floor attribute, and location different than “living-room” or without any location attribute

filter=not(eq(attributes/floor,"upper floor"),eq(attributes/location,"living-room"))

note When using a negating expression, such as not or ne, (not equal) please keep in mind that you might experience a longer time to get the response. Compared to other search operators we observed longer response times ourselves.

Parameter: option

Optional parameter defining one or more options like sorting or pagination:

Sort option

 sort(<+|-><property>,<+|-><property>,...)
  • Use + for an ascending sort order (URL encoded character %2B)
  • Use - for a descending sort order (URL encoded character %2D)

Example - sort the list ascending by the thing ID

 sort(+thingId)

Example - sort the list ascending by an attribute **

 sort(+attributes/location)

Example - multiple sort options

 sort(-attributes/location,+thingId)

This expression will sort the list descending by location attribute.
In case there are multiple things with the same location attribute, these are sorted ascending by their ID.

Comparison of string values

note Please note that the comparison of string values is supported by the API, but its behavior is not specified and may change in future releases.

Paging option

 limit(<offset>,<count>)

Limits the search results to <count> items, starting with the item at index <offset>.

  • If the paging option is not explicitly specified, the default value limit(0,25) is used, i.e. the first 25 results are returned.
    * The maximum allowed count is 200.

Example - return the first ten items

 limit(0,10)

Example - return the items 11 to 20

 limit(10,10)

i.e. Return the next ten items (from index 11 to 20)

Complex Search Examples

Search for all things located in “living-room”, reorder the list to start with the lowest thing ID as the first element, and return the first 5 results.

/api/1/search/things?filter=eq(attributes/location,"living-room")&option=sort(+thingId),limit=(0,5)

note Note that the not operator is rather slow. It is a better choice to find the Things based on Thing-specific features or attributes instead.

Imprint Legal info Privacy statement