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.
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:
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
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.
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.
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:
To retrieve compressed data add the header "Accept-Encoding: gzip" to your request.
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: