HTTP API Search

Edit this page

You search for Things using RQL expressions against the HTTP search endpoint, with support for filtering, sorting, paging, and field selection.

TL;DR: Send GET or POST requests to /api/2/search/things with filter, option, fields, and namespaces parameters to find and retrieve Things matching your criteria.

Note: Find the HTTP API reference at the Search resources.

Overview

The search endpoint is:

http://localhost:8080/api/2/search/things

If you omit the filter parameter, the result contains all Things the authenticated user is allowed to read. For details on the underlying search concepts, see Basic Search.

How it works

You pass search criteria as query parameters (for GET) or as a x-www-form-urlencoded body (for POST):

Parameter	Purpose
`filter`	RQL filter expression to select Things
`option`	RQL sorting and paging options
`fields`	Field selector for response projection
`namespaces`	Comma-separated list of namespaces to search within

Examples

Search with GET

Find Things in the living room, sorted by ID, limited to 5 results:

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

Restrict search to specific namespaces:

GET .../search/things?filter=eq(attributes/location,"living-room")&namespaces=org.eclipse.ditto,foo.bar

Return only the thingId and manufacturer attribute:

GET .../search/things?filter=eq(attributes/location,"living-room")&fields=thingId,attributes/manufacturer

Search with POST

POST requests accept the same parameters as x-www-form-urlencoded body content:

POST .../search/things
body: filter=eq(attributes/location,"living-room")&option=sort(+thingId),limit(0,5)

Use POST when your query string would be too long for a URL.

Count Things

Get the number of Things matching a filter:

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

Or with POST:

POST .../search/things/count
body: filter=eq(attributes/location,"living-room")