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:
 
Status Codes:
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:
 
Status Codes:
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:
 
Status Codes:
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:
 
Status Codes: