Edit this page

The search aspect of Ditto can be accessed via an HTTP API.

The concepts of the RQL expression, RQL sorting and RQL paging are mapped to HTTP as

  • query parameters which are added to GET requests to the search endpoint;
  • a x-www-form-urlencoded body which is added to POST requests to the search endpoint.
http://localhost:8080/api/2/search/things

If the filter parameter is omitted, the result contains all Things the authenticated user is allowed to read.

Optionally a namespaces parameter can be added to search only in the given namespaces.

GET

Query parameters

In order to define for which Things to search, the filter query parameter has to be added.
In order to change the sorting and limit the result (also to do paging), the option parameter has to be added. Default values of each option is documented here.

Complex example:

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

Another Complex example with the namespaces parameter:

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

The HTTP search API can also profit from the partial request concept of the API:
Additionally to a filter and options, a fields parameter may be specified in order to select which data of the result set to retrieve.

Example which only returns thingId and the manufacturer attribute of the found Things:

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

With the namespaces parameter, the result can be limited to the given namespaces.

Example which only returns Things with the given namespaces prefix:

GET .../search/things?namespaces=org.eclipse.ditto,foo.bar

Search count

Search counts can be made against this endpoint:

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

Complex example:

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

POST

x-www-form-urlencoded

In order to define for which Things to search, the key filter has to be used.
In order to change the sorting and limit the result (also to do paging), the key option has to be used. Default values of each option is documented here.

Complex example:

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

Another Complex example with the namespaces parameter:

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

The HTTP search API can also profit from the partial request concept of the API:
Additionally to a filter and options, the key fields may be specified in order to select which data of the result set to retrieve.

Example which only returns thingId and the manufacturer attribute of the found Things:

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

With the namespaces parameter, the result can be limited to the given namespaces.

Example which only returns Things with the given namespaces prefix:

POST .../search/things
body: namespaces=org.eclipse.ditto,foo.bar

Search count

Search counts can be made against this endpoint:

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

Complex example:

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