Rest API

Sensei requests are JSON objects sent to an end-point via HTTP POST

References

Rest end-point

Every Sensei node has a rest end-point at the /sensei path listening on the broker port, specified in the sensei.properties file, e.g.

sensei.broker.port = 8080
An example of the end-point is http://localhost:8080/sensei

Sensei Request

The request API is modeled closely after the ElasticSearch Query DSL.

A Sensei Request is represented as a JSON object, see reference.

	{
		  "query" : {
		    "query_string" : { 
		      "query" : "cool car"
		    }
		  },  

		  "selections" : [
		    {
		      "term" : "color",
		      "value" : "red"
		    }
		  ]
	}
	
and can be POSTed to the Rest end-point, e.g.

curl -X -POST -d '{"query":{"query_string" : {"query":"cool car"}},"selections": [{"term":"color","value":"red"}]}' 'http://localhost:8080/sensei'

Example

The following example shows how to make an ajax call to a Sensei rest end-point in a web page using jquery.

  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 
  <html xmlns="http://www.w3.org/1999/xhtml">

	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
		<script src="http://code.jquery.com/jquery-1.4.4.js"></script>
	</head>
	<body>
		<script type="text/javascript">
		  var url = "http://localhost:8080/sensei"
		  var senseiReq = {};
		  senseiReq.query = {};
		  senseiReq.query.query_string = {"query" : "cool car"};
		
		  senseiReq.selections = [{"term":"color","value":"red"}];
		
		  // cross-domain is allowed by the Sensei Rest end-point
		  $.post("http://localhost:8080/sensei", JSON.stringify(senseiReq),
		   function(result) {
			console.log(result);
		   });
	    </script>
	</body>
  </html>

Query via BQL

It is also possible to query a Sensei cluster using BQL.

Simply post to the above Rest end-point with a JSON object containing a bql query, example:

{
  "bql":"select color where category in ('van','exotic') order by price"
}

Get using primary keys

Another common query Sensei support is Get/GetAll using UIDs.

Given a list of UIDs, encode them into a JSON array, e.g.

  [uid1,uid2,uid3]
and post to the end-point /sensei/get, e.g. http://localhost:8080/sensei/get