Updating your Senseboard

Developers Documentation

Overview

Before you start

The Sen.se API uses many of the standards ways of doing things of other APIs you may be familiar with. It's currently based on HTTP requests, and its design is REST inspired.

The base URL for accessing the Sen.se API is http://api.sen.se

All requests are simple GET or POST requests that return JSON responses.

Authentication is based on a simple mecanism involving a key unique to a User. You key can be found under your 'Profile & settings' page.

Rate limiting

The usage of the API is subject to rate limiting

All of this being very new to us, we're monitoring how you use our API to ensure fair usage of the Platform.

If you feel you're being throttled and would like to discuss it with us, write us at api@sen.se and give us the key you're using, your Sen.se account and why you need an increased cap.

Responses

Response always use the JSON format and depend on the request made to the API.

Throughout this documentation, we'll show you response examples for each possible request to the API.

For example, a response to a request for the last event of a Feed (see 'Concepts and vocabulary') would look like :

[
    {
        "id": __event_id__,
        "value": __event_value__,
        "unit": __event's unit__,
        "timetag": __event_timestamp__,
        "publish_id": __pubsub publish id__,
        "feed_id": __feed_id__
    }
]
                    

Errors

As much as possible, Sen.se tries to use appropriate HTTP status code to indicate the general class of a problem :

200 (OK)

Request processed successfully

400 (Bad request)

Any case where a parameter is invalid, or a required parameter is missing. Additional information might be available, like when you try to access a resource that doesn't belong to you.

404 (Not found)

Resource does not exist (bad URL, path, ...).

500 (Internal Server Error)

Sen.se servers are not in good shape. The request might be valid, but needs to be retrieved later.

Concepts and vocabulary

User

That's a person that owns an account on Sen.se.

Device

A Device is a physical object. It can be an Arduino, a coffee-machine, a TV, a chair; basically if you can touch it, we call it a "Device".

Each Device you connect to Sen.se is registered on the Platform with its name, description...(and more information we'll talk about below).

In order to connect your Device to Sen.se, it needs to be able to communicate with our Platform, either directly or through a relay.

Devices connected to our platform are then generally ethernet enabled, or Wifi, Zigbee, USB...

A connected Device will then send to our Platform the data it captures: its state, its activity, information about its environment.

This Device will also be able to get data from the Platform.

Every Device has its "Device id" on Sen.se, which is the identifier of that Device on the Platform.

This Device id is used to identify the Device in API calls.

Event

Events are the atoms of Sen.se, and what it's all about.

Every time something happens that your connected Device would like to report, it sends an "Event" to the Platform. These Events are stored by Sen.se, and can be used by other Devices or Applications to trigger defined actions.

Sending an Event is called "publishing" an Event.

Feed

The Feed is where you store Events of a similar nature, or coming from the same sensor or destined to the same actuator.

The general "hierarchy" of information on Sen.se is the following :

First there is a User.
This user has Devices attached to his/her account.
Each of these Devices has one or several Feeds.
Each of these Feeds is where Events are placed and stored.

User > Device > Feed > Event

Each Device has at least one Feed, and of course can have several Feeds.

In general a Device has as many Feeds that it has sensors and actuators.

Let's say you have an Arduino with a temperature sensor, a humidity sensor and a RGB LED.

You would create a device named "Arduino", and declare three feeds for this device :

* temperature feed
* humidity feed
* LED feed

When your Arduino is reading from the temperature sensor that the temperature is 25°C, it would then send a new Event to the platform with this new data.

This Event would then be stored in the temperature Feed.

Every Feed has its Feed id on Sen.se, which is the identifier of the Feed on the Platform.

This Feed id is used to identify the Feed in API calls.

Input / Output Feed

As stated above, a Feed is dedicated to a sensor or an actuator of a Device.

To be more accurate, a sensor will generate an input Feed, when an actuator will generate an output Feed :

sensor <=> input Feed
actuator <=> output Feed

From the platform's perspective, Events of an input Feed come from the Device toward the Platform.

Events in an output Feed go from the Platform toward the Device.

Publishing / Retrieving events

Authentication

Every communication between your Device and Sen.se is protected with a Sen.se key.

This key is specific and unique to each User, and you should not share this key with others.

You can find this key in the Profile & Settings section, accessible through a link at the top right of the page.

Two methods are available for Device authentication :

* passing the Sen.se key in the header of each HTTP request:

sense_key = "YOUR_SEN.SE_KEY"

* passing the Sen.se key as a request parameter :

http://api.sen.se/events/?sense_key=YOUR_SEN.SE_KEY

No matter what method you want to use, you need to set the content-type as "application/json" in the header of your http request :

header = {"Content-type": "application/json"}

Publishing Events

POST
/events/
Required
JSON
{
"feed_id": 18400,
"value": 25
}
{
  "feed_id": 18400,
  "value": "25",
  "publish_id": "004cafcdcc0b052",
  "id": "004cafcdcc0b052",
  "timetag": "2012-10-01T10:28:11.027+00:00"
}

You may also specify a timetag in order to post events at a particular point in time.

{
"feed_id": 18400,
"value" : 25,
"timetag":"2013-01-28T09:11:00.000+00:00"
}

If you want to send several Events on different Feeds at one time, your POST should look like this:

[
    {
        "feed_id": __feed_id__,
        "value": __event_value__
    },
    {
        "feed_id": __another_feed_id__,
        "value": __another_event_value__
    }
]
                

Get Feed last Event

GET
/feeds/__feed_id__/last_event/
Required
JSON
{
  "feed_id": __feed_id__,
  "value": "25",
  "publish_id": "004cafcdcc0b052",
  "id": "004cafcdcc0b052",
  "timetag": "2012-10-01T10:28:11.027+00:00"
}

Get Feed Events

GET
/feeds/__feed_id__/events/
Required
JSON
[
  {
    "publish_id": "004cad80cdde80c",
    "value": "25",
    "feed_id": 18400,
    "id": 208801455,
    "timetag": "2012-10-01T10:10:04+00:00",
    "unit": "°C"
  },
  {
    "publish_id": "004cad80de4ef0c",
    "value": "28",
    "feed_id": 18400,
    "id": 208801849,
    "timetag": "2012-09-29T14:33:21+00:00",
    "unit": "°C"
  },
  ...
]

Get Device last Event

GET
/devices/__device_id__/last_event/
Required
JSON
{
  "publish_id": "004cafce0a39a18",
  "value": "25",
  "feed_id": 18400,
  "id": 211658920,
  "timetag": "2012-10-01T10:29:16+00:00",
  "unit": "°C"
}

Get Device events

GET
/devices/__device_id__/events/
Required
JSON
[
  {
    "publish_id": "004cad80cdde80c",
    "value": "25",
    "feed_id": 18400,
    "id": 208801455,
    "timetag": "2012-09-29T14:33:04+00:00",
    "unit": "°C"
  },
  {
    "publish_id": "004cad80de4ef0c",
    "value": "26",
    "feed_id": 18400,
    "id": 208801849,
    "timetag": "2012-09-29T14:33:21+00:00",
    "unit": "°C"
  },
  ...
]

Additional query parameters

Each API calls described above can use additional parameters to filter the query.

Parameter Usage Accepted values
limit number of results to return (default : 100, max:1000) Positive integer
offset used to page through results Positive integer
order_by order results according to this parameter id, -id, timetag, -timetag
gt retrieve events which occurred after the specified date. use with order_by=timetag Datetime, ISO 8601 formatted (e.g. 2012-10-01T08:00:00+01:00)
lt retrieve results which occurred before the specified date. use with order_by=timetag Datetime, ISO 8601 formatted (e.g. 2012-10-01T08:00:00+01:00)
exact exact value matching, use with order_by datetime if order_by timetag, id_number if order_by id
© Sen.se 2014 - Blog - Developers documentation - Forum - Contact -