Examples

This page lists some simple ways to interact with the SicsthSense system via command line (such as with cURL, wget or any other simple http client). This behaviour can be very easily implemented programatically in the language of your choice using an HTTP library. Examples just use HOST as placeholder for the hostname of the service you are using (probably either sense.sics.se or localhost if you are running your own copy). Variables are represented by all caps, e.g. USERID and RESOURCEID, they should be replaced with the class unique identifiers.

Register a user

$ curl -X POST -H "Content-Type: application/json" \
 -d '{"username":"alice", "email":"[email protected]"}' http://HOST:8080/users

This will return the USERID of the new user.

Register a new resource for the user

A new resource can then be registered for polling and/or posting:

$ curl -X POST -H "Content-Type: application/json" \
 -d '{"label": "resourceLabel", "polling_url":"http://datasource.com/test.json", "polling_period":100}' \
 http://HOST:8080/users/USERID/resources

This will return the RESOURCEID of the new resource. The SicsthSense engine will then proceed to poll the URL every polling_period seconds.

Post some data

Post a JSON data file and have the resource automatically create corresponding parsers and output streams.

$ curl -X POST -H "Content-Type: application/json" \
 -d '{"temperature": 20.1, "humidity": 10}' http://HOST:8080/users/USERID/resources/RESOURCEID/data

This will create a parser for each JSON primitive in the first POST to the resource, and corresponding output stream. One of each for /temperature and one of each for the /humidity. If you would like to only parse and store a single JSON primitive, then it is best to manually create your parsers and streams. Note: once a resource has been interacted with, auto-creation of parsers/streams will not work.

Alternatively a stream can be posted to directly, without being interpreted by any parsers. This will require the use of some simple formatting for the JSON data file.

$ curl -X POST -H "Content-Type: application/json" \
 -d '{"value": 20.1, "timestamp": 10}' http://HOST:8080/users/USERID/resources/RESOURCEID/streams/STREAMID/data

If the timestamp is not specified, then SicsthSense will attach a timestamp itself. We store dates as milliseconds since the start of 1970 UTC (similar to Unixtime).

To make the posting process more efficient, a stream can be posted to using atmosphere websockets just send the JSON to the corresponding url: http://HOST:8080/users/USERID/resources//RESOURCEID/streams/STREAMID/ws Multiple JSON datapoints can be sent through a persistent websocket, saving on resources and simplifying the posting process.

Retrieve data

Datapoints can be retrieved by simple get to the following URL:

$ curl http://HOST:8080/users/USERID/resources/RESOURCEID/streams/STREAMID/data

Which will return a JSON representation of the last 100 datapoints.

Specific data request

It is possible to request variable amounts of data points by using the query parameter limit. For example, to only get the last 10 data points, get the following:

$ curl http://HOST:8080/users/USERID/resources/RESOURCEID/streams/STREAMID/data?limit=10

All data since a given time can also be requested using the query parameter from. The supplied value should be a time in seconds since the beginning of 1970:

$ curl http://HOST:8080/users/USERID/resources/RESOURCEID/streams/STREAMID/data?from=1385763270458

The query parameter until can also be supplied to constrain the time period:

$ curl http://HOST:8080/users/USERID/resources/RESOURCEID/streams/STREAMID/data?from=1385763000000&until=1385764000000

If both limit and from/until parameters are given, the limit option will take precedence.

Authentication

Data is not public by default, so users must provide credentials when accessing non-public data. Any configuration requires people to provide their user key. The user's key is a randomly generated string available in the user profile. Simply appending it as a query parameter to the URL when making a request will identify you as being that user.

$ curl http://HOST:8080/users/USERID/resources/RESOURCEID?key=XXXXX

Accessing or posting data to the system requires the key of that resource/stream

$ curl http://HOST:8080/users/USERID/resources/RESOURCEID/streams/STREAMID/data?key=XXXXX

Websocket

If a websocket is opened to the URL http://HOST:8080/users/USERID/resources/RESOURCEID/streams/STREAMID/ws, then the connection will stay open, delivering each JSON data point in real time. This avoid polling and gives immediate access to new data.