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
GETrequests to the search endpoint; - a x-www-form-urlencoded body which is added to
POSTrequests 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")