About the API

The CommonSense API conforms to the REST design principles and is therefore based on HTTP Requests. The HTTP requests that are supported are: GET, PUT, POST, DELETE, and OPTIONS. These methods are for listing, updating, creating, and deleting data respectively. The OPTIONS method enables third party web clients to do cross-domain requests.

PUT / DELETE Alternative

Clients that are not able to perform PUT or DELETE requests can use the POST parameter _METHOD to specify the request method. An example how to delete a sensor via a POST request:

https://api.sense-os.nl/sensors/1?_METHOD=DELETE

HTTP status codes

In response to one of the HTTP requests the API will respond with one of these HTTP status codes:

200 OK - the request was successful
201 Created- the object was created successfully (only for POST requests)
403 Forbidden - not authorised for this request
404 Not Found - the resource could not be found for this user
409 Conflict - the supplied input was incorrect
500 Internal Server Error - the request could not be processed, please contact us
509 Bandwidth Limit Exceeded - you have reached the request limit of your account

Content Type

The CommonSense API supports two types of contents for uploading data: JSON and HTML form data.

When uploading data either one of these Content-Type headers should be provided:

Content-Type: application/json  
Content-Type: application/x-www-form-urlencoded  

When uploading JSON structured data the Content-Type header can be omitted if .json is added to the request url, e.g. https://api.sense-os.nl/sensors.json.

Return Formats

Currently the API only supports JSON as the ouput data structure.
The Accept header in the request should therefore at least accept json:

Accept: application/json  
Accept: *

When using a POST request, the result should be read from the Location header.

Data Compression

The API supports sending and retrieving compressed request data in gzip format. For this the default HTTP compression mechanism is used.

Compressed data can be sent by:

  • first compressing the request body data using gzip
  • adding the header "Content-Encoding: gzip"
  • adding the Content-Length header (or use chunked transfer encoding)

To retrieve compressed data add the header "Accept-Encoding: gzip" to your request.

Request Rate Limits

CommonSense has three account types and each type has access to different API features (see accounts.sense-os.nl).

The API request rate limit for the different accounts are:

  • Apprentice
    • 30 POST/min
    • 120 GET/min
    • 50MB upload/month
  • Sensei
    • 60 POST/min
    • 240 GET/min
    • 900MB upoad/month
  • True Sensei
    • 180 POST/min
    • 480 GET/min
    • 2000MB upload/month