RESTful API Documentation¶
This section documents the RESTful API offered by Little Sense. Using the URI endpoints listed below you can add and examine data collected by sensor devices on your network.
Summary¶
Resource | Operation | Description |
---|---|---|
Add reading | PUT /api/readings/ | Add a new reading. |
Device | GET /api/device/(string:device_id) | Get individual device info. |
Device Collection | GET /api/devices | Get collection of devices. |
Readings Collection | GET /api/readings/ | Get collection of readings. |
API Details¶
-
GET
/api/device/
(string: device_id)¶ List Devices
Example request:
GET /api/device/test_device_1 HTTP/1.1 Host: littlesense.local Accept: application/json
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "registered": false, "last_upd_keys": [ "int_light_level_lux", "float_signal_db", ], "device_id": "test_device_1", "last_update": { "int_light_level_lux": 135, "float_signal_db": 3.6, "time": "2018-03-20T13:52:22Z", }, "fields": [ { "dtype": "int", "unit": "lux", "id": "int_light_level_lux", "is_string": false, "is_boolean": false, "name": "Light level", "is_numeric": true }, { "dtype": "float", "unit": "db", "id": "float_signal_db", "is_string": false, "is_boolean": false, "name": "Signal", "is_numeric": true } ] }
Response Headers: - Content-Type – application/json
Status Codes: - 200 OK – device found
- 404 Not Found – device not found
-
GET
/api/devices
¶ List Devices
Example request:
GET /api/devices/ HTTP/1.1 Host: littlesense.local Accept: application/json
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json [ { "device_id": "test_device_1", "fields": [ { "is_numeric": true, "unit": "db", "is_string": false, "dtype": "float", "id": "float_audio_level_db", "name": "Audio level", "is_boolean": false }, { "is_numeric": true, "unit": "db", "is_string": false, "dtype": "float", "id": "float_signal_db", "name": "Signal", "is_boolean": false } ], "last_upd_keys": [ "float_audio_level_db", "float_signal_db", ], "last_update": { "float_audio_level_db": 1.3, "float_signal_db": 4.5, }, "registered": false }, ]
Query Parameters: - filter – Filter results by “registered” or “unregistered
Response Headers: - Content-Type – application/json
Status Codes: - 200 OK – posts found
-
GET
/api/readings/
¶ Query readings from one or more device
Example request:
GET /api/readings HTTP/1.1 ?start=2018-03-20T13%3A30%3A00Z &end=2018-03-20T13%3A35%3A00Z &fill=none &interval=5 &metric[]=test_device_2,float_temp_c,mean &metric[]=test_device_2,bool_switch_state,count Host: littlesense.local Accept: application/json
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "device_ids": [ "test_device_2" ], "count": 2, "readings": [ { "test_device_2__count__bool_switch_state": 2, "test_device_2__mean__float_temp_c": 22.54, "time": "2018-03-20T13:34:35Z" }, { "test_device_2__count__bool_switch_state": 2, "test_device_2__mean__float_temp_c": 31.25, "time": "2018-03-20T13:34:40Z" } ], "field_ids": [ "test_device_2__count__bool_switch_state", "test_device_2__mean__float_temp_c" ], "fields": { "test_device_2__count__bool_switch_state": { "is_numeric": false, "dtype": "bool", "is_string": false, "id": "bool_switch_state", "name": "Unregistered: Count Switch", "is_boolean": true, "unit": "state" }, "test_device_2__mean__float_temp_c": { "is_numeric": true, "dtype": "float", "is_string": false, "id": "float_temp_c", "name": "Unregistered: Mean Temp", "is_boolean": false, "unit": "c" } }, "end": "2018-03-20 13:35:00+00:00", "start": "2018-03-20 13:30:00+00:00" }
Query Parameters: - fill – Fill mode specifies what to do if there is no data for an interval. If set to “null” then an interval reading will be returned but with a null value. If “none” then no reading will be returned for the interval.
- interval – Interval must be an integer of seconds. The results will be grouped into intervals and the aggregation function applied.
- start – Start of reading period (inclusive)
- end – End of readings period (inclusive)
- limit – Limit the number of results
- format – Results format. Default is as a list. by_time = dict where key is timestamp and value is a dict of field:value pairs
- metrics[] – &metric[]=device_is,field_id,aggregation_function can use multiple &metric[]’s in call
- device_id – Optional device id (replaces need for metric)
Response Headers: - Content-Type – application/json
Status Codes: - 200 OK – query successful found
- 404 Not Found – device not found
- 400 Bad Request – invalid metrics
-
PUT
/api/readings/
¶ Add reading for device
Example request:
POST /api/readings HTTP/1.1 Host: littlesense.local Accept: application/json
Example response:
HTTP/1.1 200 OK Vary: Accept Content-Type: application/json { "success": true }
Query Parameters: - device_id – Device ID e.g. test_device_id
- utc – UTC timestamp string e.g. 2018-03-20T13:30:00Z. If absent or set to “NOW”, the server will add a timestamp on receiving.
- field – Field ID e.g. float_light_level_lux
- dtype – Field data type e.g. float or int
- unit – Field messurement unit e.g. lux or C
- value – Value to record
Response Headers: - Content-Type – application/json
Status Codes: - 200 OK – query successful found
- 400 Bad Request – invalid request