OpenChirp API Reference

The document specifies a RESTful API for interacting with the OpenChirp infrastructure. Usage of the API is via the HTTP protocol. All operations are defined as GET, POST, PUT, DELETE on resource URLs. Some examples of resources in the OpenChirp software stack are Location, Device, Gateway, Service etc. All these resources are represented in JSON.

Errors

The OpenChirp REST API uses the following error codes:

HTTP Error Code	Meaning
400	Bad Request – The json in request body is not well-formed.
401	Unauthorized – Invalid credentials.
403	Forbidden – Logged in user does not have permissions to do this operation.
404	Not Found
500	Internal Server Error
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Location

Create new Location

Example Request:

POST /api/location/582e2b2c065b2545ded3aabd HTTP/1.1
{
  "name":"CIC",
  "type":"BUILDING",
    "geo_loc": {
      "coordinates": [
        40.4509146,
        -79.9024777
      ]     
    }    
}

Example Response:

{
    "_id": "58d2ce918113446f5c8c28b8",
    "updated_at": "2017-03-29T21:18:42.684Z",
    "created_at": "2017-03-22T19:20:49.271Z",
    "owner": "58d2ce808113446f5c8c28b7",
    "name": "CIC",
    "__v": 0,
    "test": false,
    "type":"BUILDING",
    "geo_loc": {
      "coordinates": [
        40.4509146,
        -79.9024777
      ],     
      "type": "Point"
    },
    "id": "58d2ce918113446f5c8c28b8"
  }

HTTP Request

POST /api/location/<parentLocationId>

Request Parameters

Parameter	Description
parentLocationId	ID of parent location

Request body

Name	Type	Description	Required	Default
name	String	Name of location	Yes	-
type	Enum {BUILDING, INDOOR}	If the location is a building or an indoor location inside a building. If this location is a building, then geoLoc should be set	No	-
test	Boolean	If set to true, then the location is not visible in tree	No	False
geo_loc.type	String	Type of geo-location : Point, Line etc	No	Point
geo_loc.coordinates	Number	Coordinates are in format [longitude, latitude]	No	-

Get details of a location

Example Request :

GET /api/location/582e2b2c065b2545ded3aabd HTTP/1.1

Example Response :

{
    "_id": "58d2ce918113446f5c8c28b8",
    "updated_at": "2017-03-29T21:18:42.684Z",
    "created_at": "2017-03-22T19:20:49.271Z",
    "owner": "58d2ce808113446f5c8c28b7",
    "name": "CMU",
    "__v": 0,
    "test": false,
    "children": [
      "58d2cef38113446f5c8c28b9",
      "58d2cf008113446f5c8c28ba",
      "58dc24b2e235562ddbc9f22c"
    ],
    "geo_loc": {
      "coordinates": [],
      "type": "Point"
    },
    "id": "58d2ce918113446f5c8c28b8"
  }

HTTP Request

GET /api/location/<locationID>

Request Parameters

Parameter	Description
locationId	ID of location

Update a Location

Example Request:

PUT /api/location/582e2b2c065b2545ded3aabd HTTP/1.1

{
    "name" : "CMU Campus"
}

Example Response:

{
    "_id": "58d2ce918113446f5c8c28b8",
    "updated_at": "2017-03-29T21:18:42.684Z",
    "created_at": "2017-03-22T19:20:49.271Z",
    "owner": "58d2ce808113446f5c8c28b7",
    "name": "CMU Campus",
    "__v": 0,
    "test": false,
    "children": [
      "58d2cef38113446f5c8c28b9",
      "58d2cf008113446f5c8c28ba",
      "58dc24b2e235562ddbc9f22c"
    ],
    "geo_loc": {
      "coordinates": [],
      "type": "Point"
    },
    "id": "58d2ce918113446f5c8c28b8"
  }

HTTP Request

PUT /api/location/<locationId>

Request Parameters

Parameter	Description
locationId	ID of location to update

Request body

The request body can include one or more of the fields below that need to be updated.

Name	Type
name	String
type	Enum {BUILDING, INDOOR}
test	Boolean
geo_loc.type	String
geo_loc.coordinates	Number

Delete a location

Example Request:

DELETE /api/location/582e2b2c065b2545ded3aabd HTTP/1.1

Example Response :

HTTP/1.1 200 OK

HTTP Request

DELETE /api/location/<locationId>

Request Parameters

Parameter	Description
locationId	ID of location to delete

Get gateways at a location

Example Request:

GET /api/location/58d2cf268113446f5c8c28bc/gateways HTTP/1.1

Example Response:

[
  {
    "_id": "58dc5e8ee235562ddbc9f22e",
    "updated_at": "2017-03-30T01:25:34.907Z",
    "created_at": "2017-03-30T01:25:34.907Z",
    "owner": "58d2ce808113446f5c8c28b7",
    "name": "Lora Gateway",
    "type": "LORA",
    "location_id": "58d2cf268113446f5c8c28bc",
    "__v": 0,
    "enabled": true,
    "pubsub": {
      "protocol": "MQTT"
    },
    "id": "58dc5e8ee235562ddbc9f22e"
  }
]

HTTP Request

GET /api/location/<locationId>/gateways

Request Parameters

Parameter	Description
locationId	ID of location

Get devices at a location

Example Request:

GET /api/location/58d2cf268113446f5c8c28bc/devices HTTP/1.1

Example Response:


[
{
    _id: "598dd0330b37ba77a17bfbd0",
    name: "device1",
    location_id: "58d2cf268113446f5c8c28bc",
    pubsub: {
      protocol: "MQTT",
      endpoint: "openchirp/devices/598dd0330b37ba77a17bfbd0"
      },
    id: "598dd0330b37ba77a17bfbd0"`
}
]

HTTP Request

GET /api/location/<locationId>/devices

Request Parameters

Parameter	Description
locationId	ID of location

Recursively get all devices at all child locations

Example Request:

GET /api/location/58d2cf268113446f5c8c28bc/alldevices HTTP/1.1

Example Response:

[
  {
  _id: "598dd0330b37ba77a17bfbd0",
  name: "device floor1",
  location_id: "5985343de0d1a47181511cfe",
  pubsub: {
    protocol: "MQTT",
    endpoint: "openchirp/devices/598dd0330b37ba77a17bfbd0"
    },
  id: "598dd0330b37ba77a17bfbd0"
  },
  {
  _id: "598dd0110b37ba77a17bfbce",
  name: "device floor2",
  location_id: "59853448e0d1a47181511cff",
  pubsub: {
    protocol: "MQTT",
    endpoint: "openchirp/devices/598dd0110b37ba77a17bfbce"
  },
  id: "598dd0110b37ba77a17bfbce"
  },
  {
  _id: "598dd04f0b37ba77a17bfbd1",
  name: "device floor3",
  location_id: "5985345ce0d1a47181511d00",
  pubsub: {
    protocol: "MQTT",
    endpoint: "openchirp/devices/598dd04f0b37ba77a17bfbd1"
    },
  id: "598dd04f0b37ba77a17bfbd1"
  },
  {
  _id: "598dd01b0b37ba77a17bfbcf",
  name: "device floor4",
  location_id: "59853aa5e0d1a47181511d01",
  pubsub: {
    protocol: "MQTT",
    endpoint: "openchirp/devices/598dd01b0b37ba77a17bfbcf"
    },
  id: "598dd01b0b37ba77a17bfbcf"
  },
  {
  _id: "598dd0570b37ba77a17bfbd2",
  name: "device floor5",
  location_id: "59853aade0d1a47181511d02",
  pubsub: {
    protocol: "MQTT",
    endpoint: "openchirp/devices/598dd0570b37ba77a17bfbd2"
    },
  id: "598dd0570b37ba77a17bfbd2"
  },
  {
  _id: "598dd0660b37ba77a17bfbd3",
  name: "device floor5 2",
  location_id: "59853aade0d1a47181511d02",
  pubsub: {
    protocol: "MQTT",
    endpoint: "openchirp/devices/598dd0660b37ba77a17bfbd3"
    },
  id: "598dd0660b37ba77a17bfbd3"
  }
]

HTTP Request

GET /api/location/<locationId>/alldevices

Request Parameters

Parameter	Description
locationId	ID of location

Device

Create new Device

Example Request:

POST /api/device HTTP/1.1
{
  "name":"Lab Door",
  "location_id":"58d2cf268113446f5c8c28bc"
}

Example Response:

{
    "_id": "58dd50c4e235562ddbc9f231",
    "updated_at": "2017-03-30T19:39:56.719Z",
    "created_at": "2017-03-30T18:39:00.265Z",
    "owner": "58d2ce808113446f5c8c28b7",
    "name": "Lab Door",
    "location_id": "58d2cf268113446f5c8c28bc",
    "__v": 0,
    "enabled": true,
    "linked_services": [],
    "commands": [],
    "transducers": [],
    "pubsub": {
      "protocol": "MQTT",
      "endpoint": "/devices/58dd50c4e235562ddbc9f231"
    },
    "id": "58dd50c4e235562ddbc9f231"
  }

HTTP Request

POST /api/device

Request body

Name	Type	Description	Required	Default
name	String	Name of device	Yes	-
type	Enum {LORA, TWIST, FIREFLY, BOSCH_XDK}	Type of device.	No	-
location_id	String	Location ID	No	-
gateway_id	String	Gateway ID	No	-
enabled	Boolean	If set to false, then the device is not monitored	No	True
properties	Mixed	JSON object that can include any number of key-value pairs	No	-

Create new Device using a template

Example Request:

POST /api/device HTTP/1.1
{
  "name":"Lab Door",
  "location_id":"58d2cf268113446f5c8c28bc",
  "template_id":"58d443b5d0222f0b71c5da83"
}

Example Response:

{
    "_id": "58dd50c4e235562ddbc9f231",
    "updated_at": "2017-03-30T19:39:56.719Z",
    "created_at": "2017-03-30T18:39:00.265Z",
    "owner": "58d2ce808113446f5c8c28b7",
    "name": "Lab Door",
    "location_id": "58d2cf268113446f5c8c28bc",
    "__v": 0,
    "enabled": true,
    "linked_services": [],
    "commands": [
      {
        "name": "Open Door",
        "value": "1",
        "transducer_id": "58d2d4398113446f5c8c28c3",
        "_id": "58d2d46d8113446f5c8c28c4"
      },
      {
        "name": "Close Door",
        "value": "0",
        "transducer_id": "58d2d4398113446f5c8c28c3",
        "_id": "58d2d4798113446f5c8c28c5"
      }
    ],
    "transducers": [
      {
        "name": "Door_State",
        "unit": "Integer",
        "_id": "58d2d4398113446f5c8c28c3",
        "is_actuable": true
      }
    ],
    "pubsub": {
      "protocol": "MQTT",
      "endpoint": "/devices/58dd50c4e235562ddbc9f231"
    },
    "id": "58dd50c4e235562ddbc9f231"
  }

HTTP Request

POST /api/device

Request body

All the fields in the create device request above can be included plus a template_id which is used to create transducers, commands and linked services.

Name	Type	Description	Required	Default
template_id	String	Device template ID. All transducers, commands and linked services in the template will be added to the device.	No	-

Get details of a device

Example Request :

GET /api/device/58d445bc2881ee1032d63508 HTTP/1.1

Example Response :

{
    "_id": "58d445bc2881ee1032d63508",
    "updated_at": "2017-03-23T22:01:32.151Z",
    "created_at": "2017-03-23T22:01:32.151Z",
    "owner": "58d2ce808113446f5c8c28b7",
    "name": "Lora Device6",
    "__v": 0,
    "enabled": true,
    "linked_services": [],
    "commands": [],
    "transducers": [],
    "pubsub": {
      "protocol": "MQTT",
      "endpoint": "/devices/58d445bc2881ee1032d63508"
    },
    "id": "58d445bc2881ee1032d63508"
 }

HTTP Request

GET /api/device/<ID>

Request Parameters

Parameter	Description
ID	ID of device

Update a device

Example Request:

PUT /api/device/58d445bc2881ee1032d63508 HTTP/1.1

{
    "type": "LORA"
}

Example Response:

{
    "_id": "58d445bc2881ee1032d63508",
    "updated_at": "2017-03-23T22:01:32.151Z",
    "created_at": "2017-03-23T22:01:32.151Z",
    "owner": "58d2ce808113446f5c8c28b7",
    "name": "Lora Device6",
    "type": "LORA"
    "__v": 0,
    "enabled": true,
    "linked_services": [],
    "commands": [],
    "transducers": [],
    "pubsub": {
      "protocol": "MQTT",
      "endpoint": "/devices/58d445bc2881ee1032d63508"
    },
    "id": "58d445bc2881ee1032d63508"
 }

HTTP Request

PUT /api/device/<ID>

Request Parameters

Parameter	Description
ID	ID of device to update

Request body

The request body can include one or more of the fields below that need to be updated.

Name	Type
name	String
type	Enum {LORA, TWIST, FIREFLY, BOSCH_XDK}
location_id	String
gateway_id	String
enabled	Boolean
properties	Mixed

Delete a device

Example Request:

DELETE /api/device/582e2b2c065b2545ded3aabd HTTP/1.1

Example Response :

HTTP/1.1 200 OK

HTTP Request

DELETE /api/device/<ID>

Request Parameters

Parameter	Description
ID	ID of device to delete

Transducer

Add a transducer to a device

Example Request:

POST /api/device/582e2b2c065b2545ded3aabd/transducer HTTP/1.1
{
  "name":"Temperature",
  "unit":"Celsius",
  "properties":{
    "protobuf":"uint:32"
    }  
}

Example Response:

{
   "name": "Temperature",
   "unit": "Celsius",
   "properties": {
      "protobuf": "uint:32"
    },
   "_id": "58ddc5c9e235562ddbc9f234",
   "is_actuable": false
}

HTTP Request

POST /api/device/<deviceId>/transducer

Request Parameters

Parameter	Description
deviceId	Transducer is added to the device identified by its ID

Request body

Name	Type	Description	Required	Default
name	String	Name of transducer , example : Temperature	Yes	-
unit	String	Unit , example : Celsius	Yes	-
is_actuable	Boolean	If the transducer is actuable	No	False
properties	Mixed	JSON object that can include any number of key-value pairs	No	-

Get all transducers on a device

Example Request :

GET /api/device/582e2b2c065b2545ded3aabd/transducer HTTP/1.1

Example Response :

[
  {
    "name": "Door_State",
    "unit": "Integer",
    "_id": "58d2d4398113446f5c8c28c3",
    "is_actuable": true
  },
  {
    "name": "Temperature",
    "unit": "Celsius",
    "properties": {
      "protobuf": "uint:32"
    },
    "_id": "58ddc5c9e235562ddbc9f234",
    "is_actuable": false
  }
]

HTTP Request

GET /api/device/<deviceID>/transducer

Request Parameters

Parameter	Description
deviceID	ID of device

Update a transducer

Updating a transducer is not supported by design.

Publish to a transducer

Example Request:

POST /api/device/582e2b2c065b2545ded3aabd/transducer/58d2d4398113446f5c8c28c3 HTTP/1.1

{
"test":"Hello"
}

Example Response :

{
  "message": "Done"
}

HTTP Request

POST /api/device/<deviceID>/transducer/<transducerID>

Request Parameters

Parameter	Description
deviceID	ID of device.
transducerID	ID of transducer to publish to.

Request Body

The json in the request body is published as-is to the transducer topic.

Get values from a transducer

Example Request:

GET /api/device/590b8ab0c1d7ee2313ee421c/transducer/590cf1d043fc916594746b1b HTTP/1.1

Using cURL:

curl -G "http://openchirp.andrew.cmu.edu:7000/api/device/590b8ab0c1d7ee2313ee421c/transducer/590cf1d043fc916594746b1b"

Example Response. Returns all values in a chunked stream (chunks have a size of 10,000 points), ordered by ascending time order:

{
  "results": [
    {
      "series": [
        {
          "name": "590b8ab0c1d7ee2313ee421c_door_state",
          "columns": [
            "time",
            "value"
          ],
          "values": [

            // all values will be returned in a chunked stream 
            ...

Performing an HTTP GET to a transducer resource will return the values stored in the database in ascending time order. Additional parameters allow you to define start and end times, maximum number of returned values, and paginate through the values.

The default output format is JSON. It is possible to specify the output format using the Content-Type HTTP header, where:

text/csv or application/csv specifies CSV output
any other content type will produce JSON output (default)

HTTP Request

GET /api/device/<deviceID>/transducer/<transducerID>?[stime=<stime>&etime=<etime>&limit=<limit>&page=<page>]

Request Parameters

Parameter	Description
deviceID	ID of device.
transducerID	ID of transducer
stime	See Start and End Times
etime	See Start and End Times
limit	See Limit and Paginating
page	See Limit and Paginating

Parameters stime, etime, limit and page are not mandatory, and they can be freely combined, for example to return 5000 results (limit=5000) from a week ago (stime=now - 1w).

Start and End Times

Example Request. Return values from the last week, by passing stime=now() - 1w (note parameters are URL encoded and there must be spaces (%20) in the time specification):

GET /api/device/582e2b2c065b2545ded3aabd/transducer/58d2d4398113446f5c8c28c3%20%3Fstime%3Dnow%28%29%20-%201w HTTP/1.1

Using cURL (note the --data-urlencode and the spaces in the time specification):

curl -G "http://openchirp.andrew.cmu.edu:7000/api/device/582e2b2c065b2545ded3aabd/transducer/58d2d4398113446f5c8c28c3" --data-urlencode “stime=now() - 1w"

It is possible to define start and end times using the stime and etime query string parameters. The time specifications are according to InfluxDB.

For example, stime=now() - 1w indicates that the query will return values starting one week ago. You can use simular time specifications using ‘d’ (days), ‘h’ (hours), ‘m’ (minutes), ’s’ (seconds), ‘ms’ (milliseconds) and ‘u’ (microseconds).

Other time specification examples:

stime=stime=now() - 1w&etime=stime=now() - 1d: values from one week ago until yesterday.
stime=stime=2015-08-18 23:00:01.232000000&etime=stime=2015-09-19: values between August 18, 2015 23:00:01.232000000 and September 19, 2015 00:00:00.

Please check InfluxDB’s documentation section on Time syntax in Queries for details.

Limit and Paginating

Example Request. Return the first 5000 values from a week ago in CSV format:

GET /api/device/582e2b2c065b2545ded3aabd/transducer/58d2d4398113446f5c8c28c3%20%3Fstime%3Dnow%28%29%20-%201w%26limit%3D5000 HTTP/1.1

Content-Type: application/csv

Using cURL:

curl -H "Content-Type: application/csv" -G "http://openchirp.andrew.cmu.edu:7000/api/device/<deviceID>/transducer/<transducerID>" --data-urlencode "limit=5000" --data-urlencode "stime=now() - 1w"

You can set a limit to the number of points returned using the limit query string parameter, which can have a maximum value of 10,000 (limit=0 is equal to limit=10000).

The parameter page can be used to paginate thought the results, where each page has a size defined by the limit argument or defaults to 10,000 if no limit is given.

Delete a transducer

Example Request:

DELETE /api/device/582e2b2c065b2545ded3aabd/transducer/58d2d4398113446f5c8c28c3 HTTP/1.1

Example Response :

HTTP/1.1 200 OK

HTTP Request

DELETE /api/device/<deviceID>/transducer/<transducerID>

Request Parameters

Parameter	Description
deviceID	ID of device.
transducerID	ID of transducer to delete

Command

Create new Command

Example Request:

POST /api/device/58d445bc2881ee1032d63508/command HTTP/1.1
{
  "name":"Open Door",
  "transducer_id":"58d2d4398113446f5c8c28c3",
  "value" :"1"
}

Example Response:

{
    "name": "Open Door",
    "value": "1",
    "transducer_id": "58d2d4398113446f5c8c28c3",
    "_id": "58d2d46d8113446f5c8c28c4"
  }

HTTP Request

POST /api/device/<deviceID>/command

Request body

Name	Type	Description	Required	Default
name	String	Name of command, example: Open Door	Yes	-
transducer_id	String	Transducer to publish value to	Yes	-
value	String	Value to publish to transducer	Yes	-

Get all commands on a device

Example Request :

GET /api/device/582e2b2c065b2545ded3aabd/command HTTP/1.1

Example Response :

[
  {
    "name": "Open Door",
    "value": "1",
    "transducer_id": "58d2d4398113446f5c8c28c3",
    "_id": "58d2d46d8113446f5c8c28c4"
  },
  {
    "name": "Close Door",
    "value": "0",
    "transducer_id": "58d2d4398113446f5c8c28c3",
    "_id": "58d2d4798113446f5c8c28c5"
  }
]

HTTP Request

GET /api/device/<deviceID>/command

Request Parameters

Parameter	Description
deviceID

Execute a command

Example Request:

POST /api/device/582e2b2c065b2545ded3aabd/command/58d445bc2881ee1032d63508 HTTP/1.1

Example Response:

{ 
"message": "Done"
}

HTTP Request

POST /api/device/<deviceID>/command/<commandID>

Request Parameters

Parameter	Description
deviceID	ID of device
commandID	ID of command to execute

Update a command

Not supported.

Delete a command

Example Request:

DELETE /api/device/582e2b2c065b2545ded3aabd/command/58d445bc2881ee1032d63508 HTTP/1.1

Example Response :

HTTP/1.1 200 OK

HTTP Request

DELETE /api/device/<deviceID>/command/<commandID>

Request Parameters

Parameter	Description
deviceID	ID of command’s device.
commandID	ID of command to delete.

Service

Get all services

Example Request:

GET /api/service HTTP/1.1

Example Response:

Create new Service

Example Request:

POST /api/service HTTP/1.1
{
  "name":"InfluxDB Storage Service",
  "description": "Service that stores all device transducer data into InfluxDB"

}

Example Response:

 {
    "_id": "58d2d1a48113446f5c8c28bf",
    "updated_at": "2017-03-22T19:33:56.232Z",
    "created_at": "2017-03-22T19:33:56.232Z",
    "owner": "58d2ce808113446f5c8c28b7",
    "name": "InfluxDB Storage Service",
    "description": "Service that stores all device transducer data into InfluxDB",
    "__v": 0,
    "config_required": [],
    "pubsub": {
      "protocol": "MQTT",
      "remove_thing_endpoint": "/services/58d2d1a48113446f5c8c28bf/thing/remove",
      "update_thing_endpoint": "/services/58d2d1a48113446f5c8c28bf/thing/update",
      "new_thing_endpoint": "/services/58d2d1a48113446f5c8c28bf/thing/new",
      "endpoint": "/services/58d2d1a48113446f5c8c28bf"
    },
    "id": "58d2d1a48113446f5c8c28bf"
  }

HTTP Request

POST /api/service

Request body

Name	Type	Description	Required	Default
name	String	Name of service, example: InfluxDBStorageService.	Yes	-
description	String	A short description of what this service does.	Yes	-
properties	Mixed	Custom properties of this service. JSON object that can include any number of key-value pairs	No	-
config_required	ThingsConfig	Config required from things when they link to this service.	No	-

Get details of a service

Example Request :

GET /api/service/58d2d1a48113446f5c8c28bf HTTP/1.1

Example Response :

  {
    "_id": "58d2d1a48113446f5c8c28bf",
    "updated_at": "2017-03-22T19:33:56.232Z",
    "created_at": "2017-03-22T19:33:56.232Z",
    "owner": "58d2ce808113446f5c8c28b7",
    "name": "InfluxDB Storage Service",
    "description": "Service that stores all device transducer data into InfluxDB",
    "__v": 0,
    "config_required": [],
    "pubsub": {
      "protocol": "MQTT",
      "remove_thing_endpoint": "/services/58d2d1a48113446f5c8c28bf/thing/remove",
      "update_thing_endpoint": "/services/58d2d1a48113446f5c8c28bf/thing/update",
      "new_thing_endpoint": "/services/58d2d1a48113446f5c8c28bf/thing/new",
      "endpoint": "/services/58d2d1a48113446f5c8c28bf"
    },
    "id": "58d2d1a48113446f5c8c28bf"
  }

HTTP Request

GET /api/service/<ID>

Request Parameters

Parameter	Description
ID	ID of service

Update a service

Example Request:

PUT /api/service/582e2b2c065b2545ded3aabd HTTP/1.1

{
    "name" : ""
}

Example Response:

{

  }

HTTP Request

PUT /api/service/<ID>

Request Parameters

Parameter	Description
ID	ID of service to update

Request body

The request body can include one or more of the fields below that have to updated.

Name	Type
name	String
description	String
properties	Mixed

Delete a service

Example Request:

DELETE /api/service/582e2b2c065b2545ded3aabd HTTP/1.1

Example Response :

HTTP/1.1 200 OK

HTTP Request

DELETE /api/service/<ID>

Request Parameters

Parameter	Description
ID	ID of service to delete

Add a device to a service

Update device service config

Remove a device from a service

Get all things linked to a service

Device Template

Get all device templates

Example Request:

GET /api/devicetemplate HTTP/1.1

Example Response:

[
  {
    "_id": "58d443b5d0222f0b71c5da83",
    "updated_at": "2017-03-23T21:52:53.580Z",
    "created_at": "2017-03-23T21:52:53.580Z",
    "owner": "58d2ce808113446f5c8c28b7",
    "name": "Lora Template1",
    "description": "Template with 3 transducers with properties",
    "__v": 0,
    "linked_services": [
      {
        "service_id": "58d442c7d0222f0b71c5da82"
      }
    ],
    "transducers": [
      {
        "name": "Temperature",
        "unit": "Celsius",
        "is_actuable": false,
        "properties": {
          "protobuf": "uint:1"
        },
        "commands": []
      },
      {
        "name": "Pressure",
        "unit": "Psi",
        "is_actuable": false,
        "properties": {
          "protobuf": "uint:2"
        },
        "commands": []
      },
      {
        "name": "Voltage",
        "unit": "V",
        "is_actuable": false,
        "properties": {
          "protobuf": "uint:3"
        },
        "commands": []
      }
    ],
    "id": "58d443b5d0222f0b71c5da83"
  }
]

HTTP Request

GET /api/devicetemplate

Create new device template

Example Request:

POST /api/devicetemplate HTTP/1.1
{
  "name":"Lora Template",
  "device_id":"58d445bc2881ee1032d63508"  
}

Example Response:

HTTP Request

POST /api/devicetemplate

Request body

Name	Type	Description	Required	Default
name	String	Name of device template Yes	-
description	String	A short description of what this template contains.	Yes	-
device_id	String	ID of device from which to generate this template	Yes	-

Get details of a template

Example Request :

GET /api/devicetemplate/582e2b2c065b2545ded3aabd HTTP/1.1

Example Response :

HTTP Request

GET /api/devicetemplate/<ID>

Request Parameters

Parameter	Description
ID	ID of device template

Update a device template

Not supported.

Delete a device template

Example Request:

DELETE /api/devicetemplate/582e2b2c065b2545ded3aabd HTTP/1.1

Example Response :

HTTP/1.1 200 OK

HTTP Request

DELETE /api/devicetemplate/<ID>

Request Parameters

Parameter	Description
ID	ID of device template to delete

Gateway

Create new Gateway

Example Request:

POST /api/gateway HTTP/1.1
{
    "name": "Lora Gateway",
    "location_id": "58d2cf268113446f5c8c28bc",
    "type": "LORA"
}

Example Response:

{
    "_id": "58dc5e8ee235562ddbc9f22e",
    "updated_at": "2017-03-30T01:25:34.907Z",
    "created_at": "2017-03-30T01:25:34.907Z",
    "owner": "58d2ce808113446f5c8c28b7",
    "name": "Lora Gateway",
    "type": "LORA",
    "location_id": "58d2cf268113446f5c8c28bc",
    "__v": 0,
    "enabled": true,
    "pubsub": {
      "protocol": "MQTT"
    },
    "id": "58dc5e8ee235562ddbc9f22e"
}

HTTP Request

POST /api/gateway

Request Body

Name	Type	Description	Required	Default
name	String	Name of gateway	Yes	-
type	Enum {LORA, ZIGBEE}	Type of gateway.	Yes	-
location_id	String	Location ID
enabled	Boolean	If set to false, then the gateway is not monitored	No	True
properties	Mixed	JSON object that can include any number of key-value pairs	No	-

Get all gateways

Example Request:

GET /api/gateway HTTP/1.1

Example Response:

 [
  {
    "_id": "5873dfefc653394e3f0966b9",
    "name": "LabGateway",
    "location_id": "5833479babdafd7b34858958",
    "type": "LORA",
    "__v": 0,
    "enabled": true
  },
  {
    "_id": "587e9cf0ee4cf540f8590784",
    "name": "CICGateway",
    "location_id": "5833479babdafd7b34858958",
    "type": "LORA",
    "__v": 0,
    "enabled": true
 ]

HTTP Request

GET /api/gateway

Get details of a gateway

Example Request:

GET /api/gateway/58dc5e8ee235562ddbc9f22e HTTP/1.1

Example Response:

  {
    "_id": "58dc5e8ee235562ddbc9f22e",
    "updated_at": "2017-03-30T01:25:34.907Z",
    "created_at": "2017-03-30T01:25:34.907Z",
    "owner": "58d2ce808113446f5c8c28b7",
    "name": "Lora Gateway",
    "type": "LORA",
    "location_id": "58d2cf268113446f5c8c28bc",
    "__v": 0,
    "enabled": true,
    "pubsub": {
      "protocol": "MQTT"
    },
    "id": "58dc5e8ee235562ddbc9f22e"
  }

HTTP Request

GET /api/gateway/<gatewayID>

Request Parameters

Parameter	Description
gatewayID	ID of gateway

Get devices linked to a gateway

Example Request:

GET /api/gateway/58dc5e8ee235562ddbc9f22e/devices HTTP/1.1

Example Response:

[
  {
    "_id": "58de6b5ce235562ddbc9f235",
    "updated_at": "2017-03-31T14:44:44.557Z",
    "created_at": "2017-03-31T14:44:44.557Z",
    "owner": "58d2ce808113446f5c8c28b7",
    "name": " Lora Lab Device",
    "type": "LORA",
    "gateway_id": "58dc5e8ee235562ddbc9f22e",
    "__v": 0,
    "enabled": true,
    "linked_services": [],
    "commands": [],
    "transducers": [],
    "pubsub": {
      "protocol": "MQTT",
      "endpoint": "/devices/58de6b5ce235562ddbc9f235"
    },
    "id": "58de6b5ce235562ddbc9f235"
  }
]

HTTP Request

GET /api/gateway/<gatewayID>/devices

Request Parameters

Parameter	Description
gatewayID	ID of gateway

Update gateway

Example Request :

PUT /api/gateway/587e9cf0ee4cf540f8590784 HTTP/1.1

{
    "name" : "CICGateway_Lab"
}

Example Response :

{
    "_id": "587e9cf0ee4cf540f8590784",
    "name": "CICGateway_Lab",
    "location_id": "5833479babdafd7b34858958",
    "type": "LORA",
    "__v": 0,
    "enabled": true
}

HTTP Request

PUT /api/gateway/<ID>

Request Parameters

Parameter	Description
ID	ID of gateway to update

Request body

The request body can include one or more of the fields below that have to updated.

Name	Type
name	String
location_id	String
type	Enum
enabled	Boolean

Delete a gateway

Example Request:

DELETE /api/gateway/582e2b2c065b2545ded3aabd HTTP/1.1

Example Response :

HTTP/1.1 200 OK

HTTP Request

DELETE /api/gateway/<ID>

Request Parameters

Parameter	Description
ID	ID of gateway to delete

User

Get Logged-In User Details

Example Request:

GET /api/user HTTP/1.1

Example Response:

{
  "_id": "58d2ce808113446f5c8c28b7",
  "updated_at": "2017-03-22T19:20:32.405Z",
  "created_at": "2017-03-22T19:20:32.405Z",
  "name": "Test User",
  "email": "test@test.com",
  "__v": 0,
  "id": "58d2ce808113446f5c8c28b7"

HTTP Request

GET /api/user

Get my services

Example Request:

GET /api/user/myservices?name=influxdb HTTP/1.1

Example Response:

[
  {
    "_id": "58d2d1a48113446f5c8c28bf",
    "updated_at": "2017-03-22T19:33:56.232Z",
    "created_at": "2017-03-22T19:33:56.232Z",
    "owner": "58d2ce808113446f5c8c28b7",
    "name": "InfluxDB Storage Service",
    "description": "Service that stores all device transducer data into InfluxDB",
    "__v": 0,
    "config_required": [],
    "pubsub": {
      "protocol": "MQTT",
      "remove_thing_endpoint": "/services/58d2d1a48113446f5c8c28bf/thing/remove",
      "update_thing_endpoint": "/services/58d2d1a48113446f5c8c28bf/thing/update",
      "new_thing_endpoint": "/services/58d2d1a48113446f5c8c28bf/thing/new",
      "endpoint": "/services/58d2d1a48113446f5c8c28bf"
    },
    "id": "58d2d1a48113446f5c8c28bf"
  }
]

HTTP Request

GET /api/user/myservices?name=<search_criteria>

Request Parameters

Parameter	Description
name	Search by name (Optional)

Get my devices

Example Request :

GET /api/user/mydevices HTTP/1.1

Example Response :

[
  {
    "_id": "58d2d3078113446f5c8c28c0",
    "updated_at": "2017-03-22T19:46:01.186Z",
    "created_at": "2017-03-22T19:39:51.961Z",
    "owner": "58d2ce808113446f5c8c28b7",
    "name": "Lab Door",
    "location_id": "58d2cf268113446f5c8c28bc",
    "__v": 3,
    "enabled": true,
    "linked_services": [],
    "commands": [
      {
        "name": "Open Door",
        "value": "1",
        "transducer_id": "58d2d4398113446f5c8c28c3",
        "_id": "58d2d46d8113446f5c8c28c4"
      }
    ],
    "transducers": [
      {
        "name": "Door_State",
        "unit": "Integer",
        "_id": "58d2d4398113446f5c8c28c3",
        "is_actuable": true
      }
    ],
    "pubsub": {
      "protocol": "MQTT",
      "endpoint": "/devices/58d2d3078113446f5c8c28c0"
    },
    "id": "58d2d3078113446f5c8c28c0"
  },
  {
    "_id": "58d2d3328113446f5c8c28c1",
    "updated_at": "2017-03-30T16:07:55.655Z",
    "created_at": "2017-03-22T19:40:34.101Z",
    "owner": "58d2ce808113446f5c8c28b7",
    "name": "Buildings",
    "location_id": "58d2cf268113446f5c8c28bc",
    "type": "LORA",
    "__v": 3,
    "enabled": true,
    "linked_services": [
      {
        "service_id": "58d442c7d0222f0b71c5da82"
      }
    ],
    "commands": [],
    "transducers": [],
    "pubsub": {
      "protocol": "MQTT",
      "endpoint": "/devices/58d2d3328113446f5c8c28c1"
    },
    "id": "58d2d3328113446f5c8c28c1"
  }
 ]

HTTP Request

GET /api/user/mydevices?name=<search_criteria>

Request Parameters

Parameter	Description
name	Search by name (Optional)

Get my locations

Example Request:

GET /api/user/mylocations?name=pitt HTTP/1.1

Example Response:

[
 {  
    "_id": "58dc24b2e235562ddbc9f22c",
    "updated_at": "2017-03-30T17:55:52.406Z",
    "created_at": "2017-03-29T21:18:42.682Z",
    "owner": "58d2ce808113446f5c8c28b7",
    "name": "Pitt Campus",
    "__v": 0,
    "test": false,
    "children": [],
    "geo_loc": {
      "coordinates": [],
      "type": "Point"
    },
    "id": "58dc24b2e235562ddbc9f22c" 
  }
 ]

HTTP Request

GET /api/user/mylocations/?name=<search_criteria>

Request Parameters

Parameter	Description
name	Search by name (Optional)