Skip to content

API

Jump to bottom Edit New page
Konstantinos Vandikas edited this page Oct 8, 2015 · 99 revisions

The API handles all external calls to the system in a RESTful manner. The back-end utilizes webmachine which is written in erlang. Webmachine receives calls on port 8000 and then reroute them to the appropriate module which will handle the call. All fields are not available for all operations in the API. This is a conscious decision to prevent users from corrupting data.

##Users ##Creating a User

###Fields ####Mandatory Fields

  • username - string

####Accepted Fields

  • access_token - string
  • admin - boolean
  • description - string
  • email - string
  • firstname - string
  • image_url - string
  • lastname - string
  • notifications - object
  • password - string
  • rankings - ( rank - float , stream_id - string )
  • refresh_token - string
  • subscriptions - ( stream_id - string )
  • triggers - ( function - string, input - float, streams - string )
  • private - boolean

A user is created by doing a POST request to the API at the users tab, i.e. <API-URI>/users, where you send along a JSON object that is the user that you want to create.

###Example (webmachine running locally):

user@host ~ $ curl -XPOST 'localhost:8000/users' -H "Content-type: application/json" -d '{"description":"user","email":"[email protected]","firstname":"user","password":"u$3r","private":false,"username":"user"}'

Response:

{"_id":"user","_index":"sensorcloud","_type":"user","_version":1,"access_token":"access_token_here","created":true,"refresh_token":"refresh_token_here"}

This has now added the given user document to the system and it was assigned the id user from elastic search, the document is of type user, under index sensorcloud, the post was ok and the document now have version one.

Reading a User or listing several Users

A user is read by doing a GET request to the API at the users tab with the id of the user you want, i.e. <API-URI>/users/<username> or if you want to list all users do a GET request to the users tab, i.e. <API-URI>/users.

Example (webmachine running locally):

user@host ~ $ curl -XGET 'localhost:8000/users/username'

Response:

{"access_token":"access_token","notifications":[],"password":"","private":false,"rankings":[],"refresh_token":"refresh_token","subscriptions":[],"triggers":[],"username":"username"}

This will return the user document specified by the user name.

user@host ~ $ curl -XGET 'localhost:8000/users'

Response:

{"users":[{"access_token":"access_token","notifications":[],"password":"","private":false,"rankings":[],"refresh_token":"refresh_token","subscriptions":[],"triggers":[],"username":"username"}]}

This will return of all user documents currently in the system.

Updating a User

A user is updated by doing a PUT request to the API at the users tab with the id of the user you want to update, i.e. <API-URI>/users/<UID>. This update will happen in a field by field fashion, i.e. that a field in the document in the system will only change value if the field is specified in the update document that is passed to webmachine.

Example (webmachine running locally):

user@host ~ $ curl -XPUT 'localhost:8000/users/E9ECUfb3Q6eNq6e8d1pgUg' -H "Content-type: application/json" -d '{"username" : "Andreas"}'

Response (now):

{"_index":"sensorcloud","_type":"user","_id":"E9ECUfb3Q6eNq6e8d1pgUg","_version":1,"exists":true,"_source":{"username":"Tomas"}}

The Response should look like this, it will be changed soon:

{"ok":true,"_index":"sensorcloud","_type":"user","_id":"E9ECUfb3Q6eNq6e8d1pgUg","_version":2}

This will now update the user document with the given user id to have the new username of Andreas, all the other fields will have the same values as before the update.

Deleting a User

A user is deleted by doing a DELETE request to the API at the users tab with the id of the user you want to delete, i.e. <API-URI>/users/<UID>.

Example (webmachine running locally):

user@host ~ $ curl -XDELETE 'localhost:8000/users/E9ECUfb3Q6eNq6e8d1pgUg'

Response:

{"ok":true,"found":true,"_index":"sensorcloud","_type":"user","_id":"E9ECUfb3Q6eNq6e8d1pgUg","_version":3}

This has now deleted the user document with the given user id from the Elastic-Search data store.This should also delete all resource documents owned by the given user id and all streams and virtual streams that belong to these resources and delete all the data-points and vsdatapoints belonging to them.

##Resources ##Creating a Resource

###Fields ####Accepted Fields

  • name - string
  • description - string
  • model - string
  • manufacturer - string

A resource is created by doing a POST request to the API at the resources tab, i.e. <API-URI>/resources, where you send along a JSON object that is the resource that you want to create.

###Example (webmachine running locally):

user@host ~ $ curl -XPOST 'localhost:8000/resources' -H "Content-type: application/json" -d '{"description": "The AM2302 is a wired version of the DHT22, in a large plastic body. It is a basic, low-cost digital temperature and humidity sensor.", "manufacturer": "unknown", "model": "AM2302", "name": "AM2302"}'

Response:

{"ok":true,"_index":"sensorcloud","_type":"resource","_id":"yYiUDG6QRfiVt2ey37AuDA","_version":1}

This has now added the resource document to the system and it was assigned the id yYiUDG6QRfiVt2ey37AuDA from elastic search, the document is of type resource, under index sensorcloud, the post was ok and the document now have version one.

Reading a Resource or listing several Resources

A resource is read by doing a GET request to the API at the resources tab with the id of the resource you want, i.e. <API-URI>/resources/<UID>, listing all resources in the system is not allowed, if you want to list all resources belonging to a user do a get request to the same tab but before specify the user under the users tab, i.e. <API-URI>/users/<UID>/resources.

Example (webmachine running locally):

user@host ~ $ curl -XGET 'localhost:8000/resources/yYiUDG6QRfiVt2ey37AuDA'

Response:

{"active":"true","creation_date":"2013-09-23","description":"Temperature in Uppsala","id":"yYiUDG6QRfiVt2ey37AuDA","location":"59.8581,17.6447","make":"23","manufacturer":"Ericsson","model":"MES013","name":"Resource1","polling_freq":"20","serial":"0943123","tags":"temperature,Uppsala","type":"Temperature","uri":"http://uppsala.com","user_id":"E9ECUfb3Q6eNq6e8d1pgUg"}

This will return the resource document specified by the resource id.

user@host ~ $ curl -XGET 'localhost:8000/users/E9ECUfb3Q6eNq6e8d1pgUg/resources'

Response:

{"resources":[{"active":"true","creation_date":"2013-09-23","description":"Temperature in Uppsala","id":"yYiUDG6QRfiVt2ey37AuDA","location":"59.8581,17.6447","make":"23","manufacturer":"Ericsson","model":"MES013","name":"Resource1","polling_freq":"20","serial":"0943123","tags":"temperature,Uppsala","type":"Temperature","uri":"http://uppsala.com","user_id":"E9ECUfb3Q6eNq6e8d1pgUg"}]}

This will return of all resource documents owned by user with the given user id currently in the system.

Updating a Resource

A resource is updated by doing a PUT request to the API at the resources tab with the id of the resource you want to update, i.e. <API-URI>/resources/<RID>. This update will happen in a field by field fashion, i.e. that a field in the document in the system will only change value if the field is specified in the update document that is passed to webmachine.

Example (webmachine running locally):

user@host ~ $ curl -XPUT 'localhost:8000/resources/yYiUDG6QRfiVt2ey37AuDA' -H "Content-type: application/json" -d '{"name" : "Resource0","description":"Temperature in Uppsala Centrum"}'

Response:

{"ok":true,"_index":"sensorcloud","_type":"resource","_id":"yYiUDG6QRfiVt2ey37AuDA","_version":2}

This will now update the resource document with the given resource id to have the new name of Resource0 and the new description of Temperature in Uppsala Centrum, all the other fields will have the same values as before the update.

Searching for Resources

Resources are searched by doing a POST request to the API at the resources tab with the _search operation and sending the JSON with the query. <API-URI>/resources/_search.

Parameters:

Size - It allows you to configure the maximum amount of hits to be returned.
From - It defines the offset from the first result you want to fetch.

Example (webmachine running locally):

user@host ~ $ curl -XPOST 'localhost:8000/users/E9ECUfb3Q6eNq6e8d1pgUg/resources/_search' -H "Content-Type: application/json" -d '{"query" : {"query_string" : {"query" : "Temperature"}}}'

Response:

{"took":28,"timed_out":false,"_shards":{"total":5,"successful":5,"failed":0},"hits":{"total":1,"max_score":1.0,"hits":[{"_index":"sensorcloud","_type":"resource","_id":"ijX1afSDQcWQg3fXfkq0oQ","_score":1.0,"_source":{"user_id":"E9ECUfb3Q6eNq6e8d1pgUg","name":"Resource1","tags":"temperature,Uppsala","description":"Temperature in Uppsala","type":"Temperature","manufacturer":"Ericsson","model":"MES013","make":"23","serial":"0943123","location":"59.8581,17.6447","active":"true","uri":"http://uppsala.com","polling_freq":"20","creation_date":"2013-09-23"}}]}}

This will return all the resources from the Elastic-Search data store. In the JSON you can use all the queries types available in ElasticSearch.

Deleting a Resource

A resource is deleted by doing a DELETE request to the API at the resources tab with the id of the resource you want to delete, i.e. <API-URI>/resources/<RID>.

Example (webmachine running locally):

user@host ~ $ curl -XDELETE 'localhost:8000/resources/yYiUDG6QRfiVt2ey37AuDA'

Response:

{"ok":true,"found":true,"_index":"sensorcloud","_type":"resource","_id":"yYiUDG6QRfiVt2ey37AuDA","_version":3}

This has now deleted the resource document with the given resource id from the Elastic-Search data store. This will also delete all stream documents owned by the given resource id and should also delete all the data-points belonging to these streams but this is not implemented yet.

##Streams ##Creating a Stream

###Fields ####Accepted Fields

  • accuracy - float
  • name - string
  • tags - string
  • description - string
  • private - boolean
  • type - string
  • min_val - float
  • max_val - float
  • active - boolean
  • location - geo_point
  • resource - ( resource_id - string , uuid - string )
  • unit - string
  • uri - string
  • user - string

####Restricted Fields

  • quality - float
  • user_ranking - double
  • subscribers - integer
  • parser - string
  • polling_freq - long
  • creation_date - date
  • data_type - string

A stream is created by doing a POST request to the API at the stream tab, i.e. <API-URI>/streams, where you send along a JSON object that is the stream that you want to create. You can also do requests to <API-URI>/users/<UID>/resources/<RID>/streams and then the field "resource_id" will be added to the document with the value "rid". Creation date will soon be changed so it is generated server side so then that field should not be part of the document here.

###Example (webmachine running locally):

user@host ~ $ curl -XPOST 'localhost:8000/streams' -H "Content-type: application/json" -d '{"accuracy":"0.2","data_type":"application/json","description":"test","location":{"lat":59.357709,"lon":17.998635799999988},"max_val":"30","min_val":"-30","name":"t4","parser":"","polling":false,"polling_freq":0,"private":false,"resource":{"resource_type":"","uuid":""},"tags":"temperature","type":"test","unit":"celsius","uri":"","user_id":"user"}'

Response:

{"ok":true,"_index":"sensorcloud","_type":"stream","_id":"lEUbrYY3RT-VY-rdffE2Ug","_version":1}

This has now added the stream document to the system and it was assigned the id lEUbrYY3RT-VY-rdffE2Ug from elastic search, the document is of type stream, under index sensorcloud, the post was ok and the document now have version one. (add example for the other URI)

Reading a Stream or listing several Streams

A stream is read by doing a GET request to the API at the streams tab with the id of the stream you want, i.e. <API-URI>/streams/<SID> or if you want to list all streams do a GET request to the streams tab, i.e. <API-URI>/streams, if you want to list all streams belonging to a resource do a get request to the same tab but before specify the user and resource, i.e. <API-URI>/users/<UID>/resources/<RID>/streams.

Example (webmachine running locally):

user@host ~ $ curl -XGET 'localhost:8000/streams/lEUbrYY3RT-VY-rdffE2Ug'

Response:

{"accuracy":0.95,"active":"true","creation_date":"2013-10-01","description":"Temperature in Celsius in Norrtalje","history_size":5000,"id":"lEUbrYY3RT-VY-rdffE2Ug","last_updated":"2013-10-05T010502.0000","location":"59.7667,18.7000","max_val":50.0,"min_val":-50.0,"name":"Stream1","private":"false","resource_id":"yYiUDG6QRfiVt2ey37AuDA","subscribers":6,"tags":"temperature,celsius,Norrtalje","type":"Temperature","unit":"celsius","user_ranking":10.0}

This will return the stream document specified by the given stream id.

user@host ~ $ curl -XGET 'localhost:8000/streams'

Response:

{"streams":[{"accuracy":0.95,"active":"true","creation_date":"2013-10-01","description":"Temperature in Celsius in Norrtalje","history_size":5000,"id":"lEUbrYY3RT-VY-rdffE2Ug","last_updated":"2013-10-05T010502.0000","location":"59.7667,18.7000","max_val":50.0,"min_val":-50.0,"name":"Stream1","private":"false","resource_id":"yYiUDG6QRfiVt2ey37AuDA","subscribers":6,"tags":"temperature,celsius,Norrtalje","type":"Temperature","unit":"celsius","user_ranking":10.0}]}

This will return of all stream documents currently in the system.

user@host ~ $ curl -XGET 'localhost:8000/users/E9ECUfb3Q6eNq6e8d1pgUg/resources/yYiUDG6QRfiVt2ey37AuDA/streams'

Response:

{"streams":[{"accuracy":0.95,"active":"true","creation_date":"2013-10-01","description":"Temperature in Celsius in Norrtalje","history_size":5000,"id":"lEUbrYY3RT-VY-rdffE2Ug","last_updated":"2013-10-05T010502.0000","location":"59.7667,18.7000","max_val":50.0,"min_val":-50.0,"name":"Stream1","private":"false","resource_id":"yYiUDG6QRfiVt2ey37AuDA","subscribers":6,"tags":"temperature,celsius,Norrtalje","type":"Temperature","unit":"celsius","user_ranking":10.0}]}

This will return of all stream documents owned by resource with the given resource id currently in the system.

Retrieving all Streams that belong to a certain user

Example (webmachine running locally):

user@host ~ $ curl -XPOST localhost:8000/streams/_search -H "Content-Type: application/json" -d '{"query" : {"match" : {"user_id" : “username"}}}’

Updating a Stream

A stream is updated by doing a PUT request to the API at the streams tab with the id of the stream you want to update, i.e. <API-URI>/streams/<SID>. This update will happen in a field by field fashion, i.e. that a field in the document in the system will only change value if the field is specified in the update document that is passed to webmachine.

Example (webmachine running locally):

user@host ~ $ curl -XPUT 'localhost:8000/streams/lEUbrYY3RT-VY-rdffE2Ug' -H "Content-type: application/json" -d '{"name" : "Stream0","description":"Temperature in Uppsala Centrum in Celsius"}'

Response:

{"ok":true,"_index":"sensorcloud","_type":"stream","_id":"lEUbrYY3RT-VY-rdffE2Ug","_version":2}

This will now update the stream document with the given stream id to have the new name of Stream0 and the new description of Temperature in Uppsala Centrum in Celsius, all the other fields will have the same values as before the update.

Searching for Streams

Streams are searched by doing a POST request to the API at the streams tab with the _search operation and sending the JSON with the query. <API-URI>/streams/_search.

Parameters:

Size - It allows you to configure the maximum amount of hits to be returned.
From - It defines the offset from the first result you want to fetch.

Example (webmachine running locally):

user@host ~ $ curl -XPOST 'localhost:8000/streams/_search'  -H "Content-Type: application/json" -d '{"query" : {"query_string" : {"query" : "Norrtalje"}}}'

Response:

{"took":22,"timed_out":false,"_shards":{"total":5,"successful":5,"failed":0},"hits":{"total":1,"max_score":1.0,"hits":[{"_index":"sensorcloud","_type":"stream","_id":"EjOuve1EQ-qgD_Q55LpYLQ","_score":1.0,"_source":{"resource_id":"yYiUDG6QRfiVt2ey37AuDA","name":"Stream1","tags":"temperature,celsius,Norrtalje","description":"Temperature in Celsius in Norrtalje","private":"false","type":"Temperature","unit":"celsius","accuracy":0.95,"min_val":-50.0,"max_val":50.0,"active":"true","user_ranking":10.0,"subscribers":6,"last_updated":"2013-10-05T010502.0000", "creation_date":"2013-10-01","history_size": 5000,"location":"59.7667,18.7000"}}]}}

Deleting a Stream

A stream is deleted by doing a DELETE request to the API at the stream tab with the id of the stream you want to delete, i.e. <API-URI>/streams/<SID>.

Example (webmachine running locally):

user@host ~ $ curl -XDELETE 'localhost:8000/streams/lEUbrYY3RT-VY-rdffE2Ug'

Response:

{"ok":true,"found":true,"_index":"sensorcloud","_type":"stream","_id":"lEUbrYY3RT-VY-rdffE2Ug","_version":3}

This has now deleted the stream document with the given stream id from the Elastic-Search data store. This will also delete all the data-points owned by the given stream id.

##Data-Points ##Creating a Data-Point

###Fields ####Accepted Fields

  • stream_id - string
  • timestamp - date
  • value - double

A data-point is created by doing a POST request to the API at the data tab of the stream it belongs to, i.e. <API-URI>/streams/<SID>/data, where you send along a JSON object that is the data-point that you want to create. Timestamp will soon be changed so it is generated server side so then that field should not be part of the document here.

###Example (webmachine running locally):

user@host ~ $ curl -XPOST 'localhost:8000/streams/lEUbrYY3RT-VY-rdffE2Ug/data' -H "Content-type: application/json" -d '{"timestamp" : "20131105T114543.0000", "value" : -2.5}'

Response:

{"ok":true,"_index":"sensorcloud","_type":"datapoint","_id":"EKeFQx-FR1CyCxiL4QXpHg","_version":1}

This has now added the given data-point document to the system, with the field "streamid" added with value of the given stream id, and it was assigned the id EKeFQx-FR1CyCxiL4QXpHg from elastic search, the document is of type data-point, under index sensorcloud, the post was ok and the document now have version one.

##Creating multiple Data-Points

Even though it is not possible to create multiple data points, a simple script can be used in this case to read a set of data points from an input file and re-use the method described previously for inserting a single Data-Point in a for loop.

###Example (in python) (webmachine running locally)

from httplib2 import Http
from urllib import urlencode
import json

text = open('/home/user/data_file').read()
d = json.loads(text)
h = Http()

for datapoint in d['data'] :
	jsondump = json.dumps(datapoint)
	resp, content = h.request("http://localhost:8000/streams/stream_id_goes_here/data", "POST", jsondump)

In this example we assume that the content of the data conforms to the following json structure:

{"data":[{"timestamp":"2013-12-04T17:43:02.000","value":117.96},{"timestamp":"2013-12-04T17:47:02.000","value":117.96}]}

Reading a Data-Point or listing several Data-Points

There are different commands that can be used for reading data points.

One approach is to get all data points that belong to a stream by doing a GET request to the data tab of the stream you want the data from, i.e. <API-URI>/streams/<SID>/data.

Example (webmachine running locally):

user@host ~ $ curl -XGET 'localhost:8000/streams/lEUbrYY3RT-VY-rdffE2Ug/data'

Response:

{"data":[{"id":"EKeFQx-FR1CyCxiL4QXpHg","streamid":"lEUbrYY3RT-VY-rdffE2Ug","timestamp":"20131105T114543.0000","value":-2.5}]}

This will return of all data-point documents owned by the stream with the given stream id currently in the system.

Another approach is to do a time-span GET request which should return the data-point documents within a time period.

Example (webmachine running locally):

user@host ~ $ curl -XGET 'localhost:8000/streams/lEUbrYY3RT-VY-rdffE2Ug/data/_search?timestampFrom=2014-04-02&timestampTo=2014-04-02'

Response:

{"data":[{"id":"EKeFQx-FR1CyCxiL4QXpHg","streamid":"lEUbrYY3RT-VY-rdffE2Ug","timestamp":"20131105T114543.0000","value":-2.5}]}

Another approach leverages directly the elastic search backend and allows for a search-request-from-size which returns a specific number of results.

Example (webmachine running locally):

user@host ~ $ curl -XPOST 'localhost:8000/streams/lEUbrYY3RT-VY-rdffE2Ug/data/_search' -d '{ "from":0, "size":10 }’

Response:

{"data":[{"id":"EKeFQx-FR1CyCxiL4QXpHg","streamid":"lEUbrYY3RT-VY-rdffE2Ug","timestamp":"20131105T114543.0000","value":-2.5}]}

Searching for Data-Points

Datapoints are searched by doing a POST or GET request to the API at the data tab with the _search operation and sending the JSON with the query. <API-URI>/streams/_search.

Parameters:

timeStampFrom - Starting timestamp to be returned.
timeStampTo - It defines the offset from the first result you want to fetch.

Examples:

user@host ~ $ curl -XPOST localhost:8000/streams/Stream_Id/data/_search -d '{
		"size" : 100,
		query:{
 		   "filtered" : {
 		       "query" : {
  		          "term" : { "streamid" : Stream_Id }
  		      }, "filter" : {  "range" : {    "timestamp" : {"gte" : timestampFromValue,"lte" : timestampToValue}}}}
		 },"sort" : [{"timestamp" : {"order" : "asc"}}]  }'
user@host ~ $ curl -XGET 'localhost:8000/streams/Stream_Id/data/_search\?timestampFrom\=timestampFromValue\&timestampTo\=timestampToValue'
user@host ~ $ curl -XGET 'localhost:8000/streams/Stream_Id/data/_search\?timestampFrom\=timestampFromValue'

In both GET cases the datapoints are returned sorted.

Deleting a Data-Point

You are currently not allowed to delete data-points without also deleting the stream they are owned by so there is no call for deleting just data-points.

However, it is possible to go around this limitation in the API by addressing directly the elastic search backend using a "Delete By Query" command:

curl -XDELETE 'localhost:9200/sensorcloud/datapoint/_query?stream_id:[STREAM_ID_HERE]'

##Virtual-Streams ##Creating a Virtual-Stream

###Fields ####Accepted Fields

  • user_id - string
  • name - string
  • tags - string
  • description - string
  • private - boolean
  • streams_involved - string
  • function - string

####Restricted Fields

  • last_update - date
  • creation_date - date
  • history_size - long

A virtual stream is created by doing a POST request to the API at the vstreams tab, i.e. <API-URI>/vstreams, where you send along a JSON object that is the virtual stream that you want to create and provides information about the streams involved and the function it applies on them. Creation date will soon be changed so it is generated server side so then that field should not be part of the document here. Also, history_size and last_update will be automatically updated. The functions currently supported are "mean"(average), "total"(sum), "min", "max", "diff"(on one stream, the difference between a new value and the previous one). When posting a virtual stream, there will be an aggregation on the streams' history over time and VSdatapoints will be posted. "Diff" is not applied on the history. TimestampFrom needs to be provided and specifies a starting point for when aggregating the history of the streams. Examples: "20131105T114543.0000", "now-1h", "now-1d" etc. Finally, the user must specify the time interval for the aggregation of the history over time(as 2nd parameter in the function list). Examples: 1s, 1m etc.

###Example (webmachine running locally):

user@host ~ $ curl -XPOST 'localhost:8000/vstreams' -H "Content-type: application/json" -d '{"user_id":"my_user","name":"VStream1","tags":"average,temperature,celsius,uppsala","description":"Average Temperature in Celsius in Uppsala","private":"false","timestampfrom" : "now-1w","streams_involved": ["Ef47PMuKS3CQY9hQTxgh3g", "8Cg5YBsDT8q9M0ttVc8vHA"],"function":["mean", "2s"]}'

Response:

{"ok":true,"_index":"sensorcloud","_type":"virtual_stream","_id":"sty7PaSnSJqIt4VDtkSaHA","_version":1}

Reading a Virtual-Stream or listing several Virtual-Streams

A virtual stream is read by doing a GET request to the API at the vstreams tab with the id of the vstream asked, i.e. <API-URI>/vstreams/<VSID> or if you want to list all virtual streams do a GET request to the streams tab, i.e. <API-URI>/vstreams, if you want to list all streams belonging to a resource do a get request to the same tab but before specify the user and resource, i.e. <API-URI>/users/<UID>/resources/<RID>/vstreams.

Examples (webmachine running locally):

user@host ~ $ curl -XGET 'localhost:8000/vstreams/lEUbrYY3RT-VY-rdffE2Ug'

Response:

{"creation_date":"2013-12-17","description":"some_descr","function":["diff"],"history_size":3,"id":"weDGTMe5RvuT8XBMg-yTYw","last_updated":"2013-12-17T16:43:37.869","name":"myvstream2","streams_involved":["Ef47PMuKS3CQY9hQTxgh3g"],"timestampfrom":"now-1w","user_id":"testuser"}

This will return the virtual stream document specified by the given stream id.

user@host ~ $ curl -XGET 'localhost:8000/vstreams'

Response:

{"users":[{"creation_date":"2013-12-18","description":"some_descr","function":["mean","2s"],"history_size":5,"id":"sty7PaSnSJqIt4VDtkSaHA","last_updated":"2013-12-17T16:43:36.000","name":"myvstream2","streams_involved":["Ef47PMuKS3CQY9hQTxgh3g","8Cg5YBsDT8q9M0ttVc8vHA"],"timestampfrom":"now-1w","user_id":"testuser"},{"creation_date":"2013-12-17","description":"some_descr","function":["diff"],"history_size":3,"id":"weDGTMe5RvuT8XBMg-yTYw","last_updated":"2013-12-17T16:43:37.869","name":"myvstream2","streams_involved":["Ef47PMuKS3CQY9hQTxgh3g"],"timestampfrom":"now-1w","user_id":"testuser2"}]}

This will return of all public virtual stream documents currently in the system.

user@host ~ $ curl -XGET 'localhost:8000/users/test_user/vstreams'

Response:

{"users":[{"creation_date":"2013-12-18","description":"some_descr","function":["mean","2s"],"history_size":5,"id":"sty7PaSnSJqIt4VDtkSaHA","last_updated":"2013-12-17T16:43:36.000","name":"myvstream2","streams_involved":["Ef47PMuKS3CQY9hQTxgh3g","8Cg5YBsDT8q9M0ttVc8vHA"],"timestampfrom":"now-1w","user_id":"test_user"}]}

Reading a VSData-Point or listing several VSData-Points

A virtual stream data-point can not currently be read individually but you can list all the vsdata-points belonging to a virtual stream by doing a GET request to the data tab of the vstream you want the data from, i.e. <API-URI>/vstreams/<SID>/data.

Example (webmachine running locally):

user@host ~ $ curl -XGET 'localhost:8000/vstreams/lEUbrYY3RT-VY-rdffE2Ug/data'

Response:

{"data":[{"id":"8yqXYdnxT9ew7Bg96dR6eA","stream_id":"weDGTMe5RvuT8XBMg-yTYw","timestamp":"2013-12-17T16:43:37.869","value":3.0},{"id":"bhz-tm1oTvu901syAPoUVg","stream_id":"weDGTMe5RvuT8XBMg-yTYw","timestamp":"2013-12-17T16:42:56.311","value":6.0},{"id":"pMUdBDk6RQagPPi5Q1yj4Q","stream_id":"weDGTMe5RvuT8XBMg-yTYw","timestamp":"2013-12-17T16:43:19.184","value":10.0}]}

Searching for Virtual-Streams

Virtual Streams are searched by doing a POST request to the API at the vstreams tab with the _search operation and sending the JSON with the query. <API-URI>/vstreams/_search. Example:

curl -XPOST localhost:8000/vstreams/_search -d '{"size" : 100,query:{"term" : { "user_id" : "testuser" }} }'

Response:

{"hits":[{"creation_date":"2013-12-17","description":"blabla","function":["diff"],"history_size":3,"id":"weDGTMe5RvuT8XBMg-yTYw","last_updated":"2013-12-17T16:43:37.869","name":"myvstream2","streams_involved":["Ef47PMuKS3CQY9hQTxgh3g"],"timestampfrom":"now-1w","user_id":"testuser"}]}

Updating a Virtual-Stream

###Fields ####Accepted Fields

  • user_id - string
  • name - string
  • tags - string
  • description - string
  • private - boolean

A virtual stream is updated by doing a PUT request to the API at the vstreams tab with the id of the virtual stream you want to update, i.e. <API-URI>/vstreams/<SID>. This update will happen in a field by field fashion, i.e. that a field in the document in the system will only change value if the field is specified in the update document that is passed to webmachine. Function and streams_involved fields are not allowed to be updated, since they are the fundamental fields for the creation of the history of the virtual stream.

Example (webmachine running locally):

user@host ~ $ curl -XPUT 'localhost:8000/vstreams/nmpBX6xsTBKBx0oTUqyHJQ -d '{"user_id" : "testuser", "name" : "updated_myvstream", "description" : "updated_description"}'

Response:

{"user_id" : "testuser", "name" : "myvstream33", "description" : "blabla33"}'
{"ok":true,"_index":"sensorcloud","_type":"virtual_stream","_id":"nmpBX6xsTBKBx0oTUqyHJQ","_version":4}

This will now update the virtual stream document with the given vstream id to have a name and description, while all the other fields will have the same values as before the update.

This will return all the streams from the Elastic-Search data store. In the JSON you can use all the queries types available in ElasticSearch.

Deleting a Virtual-Stream

A virtual stream is deleted by doing a DELETE request to the API at the vstreams tab with the id of the virtual stream to be deleted, i.e. <API-URI>/vstreams/<SID>.

Example (webmachine running locally):

user@host ~ $ curl -XDELETE 'localhost:8000/vstreams/4Qrp_S3PRESLaK9jIqb6eg'

Response:

{"ok":true,"found":true,"_index":"sensorcloud","_type":"virtual_stream","_id":"4Qrp_S3PRESLaK9jIqb6eg","_version":5}

This has now deleted the vstream document with the given vstream id from the Elastic-Search data store. This will also delete all the vsdatapoints owned by the virtual stream.

General Search

In order to do a basic search through all the data in the data store, you can use the general search. Streams, groups and users are searched by doing a POST request to the API with the _search operation and sending the JSON with the query. <API-URI>/_search.

Parameters:

Size - It allows you to configure the maximum amount of hits to be returned.
From - It defines the offset from the first result you want to fetch.
Sort - It allows to add one or more sort on specific fields.

Example (webmachine running locally):

user@host ~ $ curl -XPOST 'localhost:8000/_search'  -H "Content-Type: application/json" -d '{"query" : {"query_string" : { "query" : "Norrtalje"}}}'

Response:

{"streams": {"took":12,"timed_out":false,"_shards":{"total":5,"successful":5,"failed":0},"hits":{"total":1,"max_score":1.0,"hits":[{"_index":"sensorcloud","_type":"stream","_id":"EjOuve1EQ-qgD_Q55LpYLQ","_score":1.0,"_source":{"resource_id":"yYiUDG6QRfiVt2ey37AuDA","name":"Stream1","tags":"temperature,celsius,Norrtalje","description":"Temperature in Celsius in Norrtalje","private":"false","type":"Temperature","unit":"celsius","accuracy":0.95,"min_val":-50.0,"max_val":50.0,"active":"true","user_ranking":10.0,"subscribers":6,"last_updated":"2013-10-05T010502.0000", "creation_date":"2013-10-01","history_size": 5000,"location":"59.7667,18.7000"}]
"users":{"took":12,"timed_out":false,"_shards":{"total":5,"successful":5,"failed":0},"hits":{"total":1,"max_score":1.0,"hits":[{"_index":"sensorcloud","_type":"user","_id":"E9ECUfb3Q6eNq6e8d1pgUg","_score":1.0,"_source":{"username" : "Norrtalje"}}]}}

This will return all the streams, users and groups from the Elastic-Search data store. In the JSON you can use all the queries types avaiable in ElasticSearch.

Add a custom footer
Add a custom sidebar
Clone this wiki locally