Device Management API

This document describes the APIs using DeviceManager as a standalone process. If used with other dojot’s components, the endpoints might be changed a bit. Check dojot’s documentation to check all of them.

Templates ¶

Before describing the device APIs, we must detail the template endpoints. As said before, templates are a way to describe the “device model”, or, more abstractly, a “device class”. These templates contains all the attributes that will be applied to the device. Always remember that they can (and eventually will) be merged into one to create a single device - they must not have attributes with the same name. If this is inevitable, a tag could be added to the attribute name and, while creating the device, translation instructions could be created in order to map each attribute from the incoming message to the appropriate device attribute.

Templates ¶

Register a new template
POST`/template`

Example URI

POST http://localhost:5000/template

Request

HideShow

Headers

Content-Type: application/json
Authorization: Bearer JWT

Body

{
  "label": "SensorModel",
  "attrs": [
    {
      "label": "temperature",
      "type": "dynamic",
      "value_type": "float"
    },
    {
      "label": "model-id",
      "type": "static",
      "value_type": "string",
      "static_value": "model-001"
    }
  ]
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "result": "ok",
  "template": {
    "created": "2018-02-27T14:03:48.857311+00:00",
    "data_attrs": [
      {
        "template_id": "10",
        "created": "2018-02-27T14:03:48.859440+00:00",
        "label": "temperature",
        "value_type": "float",
        "type": "dynamic",
        "id": 19
      },
      {
        "static_value": "model-001",
        "created": "2018-02-27T14:03:48.861690+00:00",
        "label": "model-id",
        "value_type": "string",
        "type": "static",
        "id": 20,
        "template_id": "10"
      }
    ],
    "label": "SensorModel",
    "config_attrs": [],
    "attrs": [
      {
        "template_id": "10",
        "created": "2018-02-27T14:03:48.859440+00:00",
        "label": "temperature",
        "value_type": "float",
        "type": "dynamic",
        "id": 19
      },
      {
        "static_value": "model-001",
        "created": "2018-02-27T14:03:48.861690+00:00",
        "label": "model-id",
        "value_type": "string",
        "type": "static",
        "id": 20,
        "template_id": "10"
      }
    ],
    "id": 10
  }
}

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": {
    "label": [
      "Missing data for required field."
    ]
  },
  "message": "failed to parse input"
}

Get the current list of templates
GET`/template{?page_size,page_num,attr_format}`

Get the full list of templates with all their associated attributes.

Example URI

GET http://localhost:5000/template?page_size=20&page_num=1&attr_format="both"

URI Parameters

HideShow

page_size: integer (optional) Example: 20
page_num: integer (optional) Example: 1
attr_format: string (optional) Example: "both"
Must be one of “both”, “single” (if ‘data_attrs’ and ‘config_attrs’ are to be omited) or “split” (if ‘attrs’ list is to be omited). ‘attrs’ field will always contain all template attributes that are listed by both ‘data_attrs’ and ‘config_attrs’.

Request

HideShow

Headers

Authorization: Bearer JWT

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "templates": [
    {
      "created": "2018-02-27T16:10:23.173565+00:00",
      "data_attrs": [
        {
          "template_id": "1",
          "created": "2018-02-27T16:10:23.175625+00:00",
          "label": "temperature",
          "value_type": "float",
          "type": "dynamic",
          "id": 1
        },
        {
          "static_value": "model-001",
          "created": "2018-02-27T16:10:23.178557+00:00",
          "label": "model-id",
          "value_type": "string",
          "type": "static",
          "id": 2,
          "template_id": "1"
        }
      ],
      "label": "SensorModel",
      "config_attrs": [],
      "attrs": [
        {
          "static_value": "model-001",
          "created": "2018-02-27T16:10:23.178557+00:00",
          "label": "model-id",
          "value_type": "string",
          "type": "static",
          "id": 2,
          "template_id": "1"
        },
        {
          "template_id": "1",
          "created": "2018-02-27T16:10:23.175625+00:00",
          "label": "temperature",
          "value_type": "float",
          "type": "dynamic",
          "id": 1
        }
      ],
      "id": 1
    }
  ],
  "pagination": {
    "has_next": false,
    "next_page": null,
    "total": 1,
    "page": 1
  }
}

Template info ¶

Access a specific template

Get template info
GET`/template/{?attr_format}`

Retrieves all information from a specific template

Example URI

GET http://localhost:5000/template/?attr_format="both"

URI Parameters

HideShow

attr_format: string (optional) Example: "both"
Must be one of “both”, “single” (if ‘data_attrs’ and ‘config_attrs’ are to be omited) or “split” (if ‘attrs’ list is to be omited). ‘attrs’ field will always contain all template attributes that are listed by both ‘data_attrs’ and ‘config_attrs’.

Request

HideShow

Headers

Authorization: Bearer JWT

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "attrs": [
    {
      "created": "2018-01-09T10:38:55.159740+00:00",
      "id": 3,
      "label": "doorStatus",
      "template_id": "2",
      "type": "dynamic",
      "value_type": "string"
    },
    {
      "created": "2018-01-09T10:38:55.160623+00:00",
      "id": 4,
      "label": "temp",
      "template_id": "2",
      "type": "dynamic",
      "value_type": "string"
    },
    {
      "created": "2018-01-09T10:38:55.161061+00:00",
      "id": 5,
      "label": "id",
      "template_id": "2",
      "type": "static",
      "value_type": "string"
    },
    {
      "created": "2018-01-09T10:38:55.161466+00:00",
      "id": 6,
      "label": "protocol",
      "template_id": "2",
      "type": "meta",
      "value_type": "string"
    },
    {
      "created": "2018-01-09T10:38:55.161874+00:00",
      "id": 7,
      "label": "topic",
      "template_id": "2",
      "type": "mqtt_meta",
      "value_type": "string"
    }
  ],
  "config_attrs": [
    {
      "created": "2018-01-09T10:38:55.161466+00:00",
      "id": 6,
      "label": "protocol",
      "template_id": "2",
      "type": "meta",
      "value_type": "string"
    },
    {
      "created": "2018-01-09T10:38:55.161874+00:00",
      "id": 7,
      "label": "topic",
      "template_id": "2",
      "type": "mqtt_meta",
      "value_type": "string"
    }
  ],
  "created": "2018-01-09T10:38:55.153648+00:00",
  "data_attrs": [
    {
      "created": "2018-01-09T10:38:55.159740+00:00",
      "id": 3,
      "label": "doorStatus",
      "template_id": "2",
      "type": "dynamic",
      "value_type": "string"
    },
    {
      "created": "2018-01-09T10:38:55.160623+00:00",
      "id": 4,
      "label": "temp",
      "template_id": "2",
      "type": "dynamic",
      "value_type": "string"
    },
    {
      "created": "2018-01-09T10:38:55.161061+00:00",
      "id": 5,
      "label": "id",
      "template_id": "2",
      "type": "static",
      "value_type": "string"
    }
  ],
  "id": 2,
  "label": "container"
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "message": "No such template: 123",
  "status": 404
}

Update template info
PUT`/template/{id}`

Replaces all attributes from a specific template. All devices based on this template will be also updated.

Example URI

PUT http://localhost:5000/template/4865

URI Parameters

HideShow

id: integer (required) Example: 4865
The template ID

Request

HideShow

Headers

Content-Type: application/json
Authorization: Bearer JWT

Body

{
  "label": "SensorModel",
  "attrs": [
    {
      "label": "led",
      "type": "dynamic",
      "value_type": "bool"
    },
    {
      "label": "fan",
      "type": "dynamic",
      "value_type": "bool"
    }
  ]
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "updated": {
    "created": "2017-12-20T18:52:34.361828+00:00",
    "attrs": [
      {
        "template_id": "4865",
        "created": "2017-12-20T18:53:19.808891+00:00",
        "label": "temperature",
        "value_type": "float",
        "type": "dynamic",
        "id": 30
      },
      {
        "template_id": "4865",
        "created": "2017-12-20T18:53:19.809999+00:00",
        "label": "pressure",
        "value_type": "float",
        "type": "dynamic",
        "id": 31
      },
      {
        "template_id": "4865",
        "created": "2017-12-20T18:53:19.810846+00:00",
        "label": "led",
        "value_type": "bool",
        "type": "dynamic",
        "id": 32
      },
      {
        "template_id": "4865",
        "created": "2017-12-20T18:53:19.811781+00:00",
        "label": "fan",
        "value_type": "bool",
        "type": "dynamic",
        "id": 33
      }
    ],
    "id": "4865",
    "label": "SensorModel"
  },
  "result": "ok"
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "message": "No such template: 123",
  "status": 404
}

Delete template
DELETE`/template/{id}`

Removes a template. If any device is based on the template being removed, then all its attributes will be also removed.

Example URI

DELETE http://localhost:5000/template/4865

URI Parameters

HideShow

id: integer (required) Example: 4865
The template ID

Request

HideShow

Headers

Authorization: Bearer JWT

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "removed": {
    "attrs": [
      {
        "created": "2017-12-27T15:22:13.331950+00:00",
        "id": 9,
        "label": "temperature",
        "template_id": "4865",
        "type": "dynamic",
        "value_type": "float"
      },
      {
        "created": "2017-12-27T15:22:13.334498+00:00",
        "id": 10,
        "label": "model-id",
        "static_value": "model-001",
        "template_id": "4865",
        "type": "static",
        "value_type": "string"
      }
    ],
    "created": "2017-12-27T15:22:13.330246+00:00",
    "id": "4865",
    "label": "SensorModel"
  },
  "result": "ok"
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "message": "No such template: 123",
  "status": 404
}

Devices ¶

All these endpoints are related to CRUD operations over devices.

Devices ¶

Register a new device
POST`/device{?count,verbose}`

Register a new device. In this example, there is already a template (ID 1) which describes all the attributes to be applied to this device.

Example URI

POST http://localhost:5000/device?count=3&verbose=False

URI Parameters

HideShow

count: integer (optional) Example: 3
verbose: boolean (optional) Example: False

Request

HideShow

Headers

Content-Type: application/json
Authorization: Bearer JWT

Body

{
  "label": "test_device",
  "templates": [
    1
  ]
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "devices": [
    {
      "id": "68fc",
      "label": "test_device_0"
    },
    {
      "id": "94dc",
      "label": "test_device_1"
    },
    {
      "id": "1ebc",
      "label": "test_device_2"
    }
  ],
  "message": "devices created"
}

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "status": "Faied to parse payload as JSON"
}

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "status": "unknown request format"
}

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "status": "device has missing fields"
}

Response 500

HideShow

Headers

Content-Type: application/json

Body

{
  "status": "failed to generate unique id"
}

Response 500

HideShow

Headers

Content-Type: application/json

Body

{
  "status": "failed to configure device"
}

Device info ¶

Access a specific device

Get device info
GET`/device/{id}`

Retrieves all information from a specific device

Example URI

GET http://localhost:5000/device/efac

URI Parameters

HideShow

id: string (required) Example: efac
The device ID

Request

HideShow

Headers

Content-Type: application/json
Authorization: Bearer JWT

Response 200

HideShow

Body

{
  "attrs": {
    "4865": [
      {
        "created": "2017-12-20T18:14:43.994796+00:00",
        "id": 30,
        "label": "tag_temperature",
        "template_id": "4865",
        "type": "dynamic",
        "value_type": "float"
      },
      {
        "created": "2017-12-20T18:14:44.014065+00:00",
        "id": 31,
        "label": "tag_pressure",
        "template_id": "4865",
        "type": "dynamic",
        "value_type": "float"
      },
      {
        "created": "2017-12-20T18:14:44.015474+00:00",
        "id": 32,
        "label": "tag_led",
        "template_id": "4865",
        "type": "dynamic",
        "value_type": "bool"
      },
      {
        "created": "2017-12-20T18:14:44.016804+00:00",
        "id": 33,
        "label": "tag_fan",
        "template_id": "4865",
        "type": "dynamic",
        "value_type": "bool"
      }
    ]
  },
  "created": "2017-12-20T18:15:08.864677+00:00",
  "id": "10cf",
  "label": "sensor-4",
  "templates": [
    "4865"
  ]
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "message": "No such device: aaaa",
  "status": 404
}

Get the current list of devices
GET`/device{?page_size,page_num,idsOnly}`

Get the full list of devices with all their associated attributes. Each attribute from attrs is the template ID from where the attributes came from. In this example, there is only one template (ID 1).

Example URI

GET http://localhost:5000/device?page_size=20&page_num=1&idsOnly=false

URI Parameters

HideShow

page_size: integer (optional) Example: 20
page_num: integer (optional) Example: 1
idsOnly: booelan (optional) Example: false
Return only the ids of all existing devices. Ignores any page_size and page_num configurations
attr: string (optional)
Return only devices that contain an attribute with given value.
label: string (optional)
Return only devices that are named by the given value.

Request

HideShow

Headers

Authorization: Bearer JWT

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "devices": [
    {
      "attrs": {
        "4865": [
          {
            "created": "2017-12-20T18:14:43.994796+00:00",
            "id": 30,
            "label": "tag_temperature",
            "template_id": "4865",
            "type": "dynamic",
            "value_type": "float"
          },
          {
            "created": "2017-12-20T18:14:44.014065+00:00",
            "id": 31,
            "label": "tag_pressure",
            "template_id": "4865",
            "type": "dynamic",
            "value_type": "float"
          },
          {
            "created": "2017-12-20T18:14:44.015474+00:00",
            "id": 32,
            "label": "tag_led",
            "template_id": "4865",
            "type": "dynamic",
            "value_type": "bool"
          },
          {
            "created": "2017-12-20T18:14:44.016804+00:00",
            "id": 33,
            "label": "tag_fan",
            "template_id": "4865",
            "type": "dynamic",
            "value_type": "bool"
          }
        ]
      },
      "created": "2017-12-20T18:15:08.864677+00:00",
      "id": "10cf",
      "label": "sensor-4",
      "templates": [
        "4865"
      ]
    }
  ],
  "pagination": {
    "has_next": false,
    "next_page": null,
    "page": 1,
    "total": 1
  }
}

Request List only device ids

HideShow

idsOnly query parameter set to true

Headers

Authorization: Bearer JWT

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  "4f2b",
  "1e4a",
  "3762"
]

Get the current list of devices associated with given template
GET`/device/template/{template_id}{?page_size,page_num}`

Get the full list of devices that belong to a given template…

Example URI

GET http://localhost:5000/device/template/4865?page_size=20&page_num=1

URI Parameters

HideShow

template_id: integer (required) Example: 4865
page_size: integer (optional) Example: 20
page_num: integer (optional) Example: 1

Request

HideShow

Headers

Authorization: Bearer JWT

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "devices": [
    {
      "attrs": {
        "4865": [
          {
            "label": "temperature",
            "type": "dynamic",
            "value_type": "float",
            "created": "2018-03-01T13:53:28.493509+00:00",
            "id": 1415,
            "template_id": "668"
          },
          {
            "label": "model-id",
            "type": "static",
            "static_value": "model-001",
            "value_type": "string",
            "created": "2018-03-01T13:53:28.494571+00:00",
            "id": 1416,
            "template_id": "668"
          }
        ]
      },
      "created": "2017-12-20T18:15:08.864677+00:00",
      "id": "10cf",
      "label": "sensor-4",
      "templates": [
        "4865"
      ]
    }
  ],
  "pagination": {
    "has_next": false,
    "next_page": null,
    "page": 1,
    "total": 1
  }
}

Update device info
PUT`/device/{id}`

Updates a device’s configuration

Example URI

PUT http://localhost:5000/device/efac

URI Parameters

HideShow

id: string (required) Example: efac
The device ID

Request

HideShow

Headers

Content-Type: application/json
Authorization: Bearer JWT

Body

{
  "label": "updated_device",
  "templates": [
    4865
  ]
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "device": {
    "attrs": {
      "4865": [
        {
          "created": "2018-02-08T09:45:31.505301+00:00",
          "id": 1,
          "label": "a",
          "template_id": "1",
          "type": "dynamic",
          "value_type": "ingeger"
        },
        {
          "created": "2018-02-08T09:45:31.507894+00:00",
          "id": 2,
          "label": "b",
          "template_id": "1",
          "type": "dynamic",
          "value_type": "integer"
        }
      ]
    },
    "created": "2018-02-08T09:51:39.506629+00:00",
    "id": "06d0",
    "label": "updated_device",
    "templates": [
      "4865"
    ],
    "updated": "2018-02-08T09:52:20.149300+00:00"
  },
  "message": "device updated"
}

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "status": "unknown request format"
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "status": "given device was not found"
}

Response 500

HideShow

Headers

Content-Type: application/json

Body

{
  "status": "failed to update device configuration"
}

Configure device
PUT`/device/{deviceid}/actuate`

Send a configuration message to the device to change some of its attributes. The target attribute must be of type “actuator”.

Example URI

PUT http://localhost:5000/device/efac/actuate

URI Parameters

HideShow

deviceid: string (required) Example: efac

Request

HideShow

Headers

Content-Type: application/json
Authorization: Bearer JWT

Body

{
  "topic": "/admin/efac/config",
  "attrs": {
    "temperature": 10.6,
    "fan": 100
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "status": "configuration sent to device"
}

Response 403

HideShow

Headers

Content-Type: application/json

Body

{
  "status": "some of the attributes are not configurable",
  "attrs": [
    "temperature"
  ]
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "status": 404,
  "message": "No such device: xyzw"
}

Delete device
DELETE`/device/{id}`

Removes a device

Example URI

DELETE http://localhost:5000/device/efac

URI Parameters

HideShow

id: string (required) Example: efac
The device ID

Request

HideShow

Headers

Content-Type: application/json
Authorization: Bearer JWT

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "removed_device": {
    "attrs": {
      "4865": [
        {
          "created": "2017-12-20T18:14:43.994796+00:00",
          "id": 30,
          "label": "tag_temperature",
          "template_id": "4865",
          "type": "dynamic",
          "value_type": "float"
        },
        {
          "created": "2017-12-20T18:14:44.014065+00:00",
          "id": 31,
          "label": "tag_pressure",
          "template_id": "4865",
          "type": "dynamic",
          "value_type": "float"
        },
        {
          "created": "2017-12-20T18:14:44.015474+00:00",
          "id": 32,
          "label": "tag_led",
          "template_id": "4865",
          "type": "dynamic",
          "value_type": "bool"
        },
        {
          "created": "2017-12-20T18:14:44.016804+00:00",
          "id": 33,
          "label": "tag_fan",
          "template_id": "4865",
          "type": "dynamic",
          "value_type": "bool"
        }
      ]
    },
    "created": "2017-12-20T18:15:08.864677+00:00",
    "id": "10cf",
    "label": "sensor-4",
    "templates": [
      "4865"
    ]
  },
  "result": "ok"
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "message": "No such device: aaaa",
  "status": 404
}

Templates ¶

Templates ¶

Register a new templatePOST/template

Example URI

Headers

Body

Headers

Body

Headers

Body

Get the current list of templatesGET/template{?page_size,page_num,attr_format}

Example URI

Headers

Headers

Body

Template info ¶

Get template infoGET/template/{?attr_format}

Example URI

Headers

Headers

Body

Headers

Body

Update template infoPUT/template/{id}

Example URI

Headers

Body

Headers

Body

Headers

Body

Delete templateDELETE/template/{id}

Example URI

Headers

Headers

Body

Headers

Body

Devices ¶

Devices ¶

Register a new devicePOST/device{?count,verbose}

Example URI

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Device info ¶

Get device infoGET/device/{id}

Example URI

Headers

Body

Headers

Body

Get the current list of devicesGET/device{?page_size,page_num,idsOnly}

Example URI

Headers

Headers

Body

Headers

Headers

Body

Get the current list of devices associated with given templateGET/device/template/{template_id}{?page_size,page_num}

Example URI

Headers

Headers

Body

Update device infoPUT/device/{id}

Example URI

Headers

Body

Register a new template
POST`/template`

Get the current list of templates
GET`/template{?page_size,page_num,attr_format}`

Get template info
GET`/template/{?attr_format}`

Update template info
PUT`/template/{id}`

Delete template
DELETE`/template/{id}`

Register a new device
POST`/device{?count,verbose}`

Get device info
GET`/device/{id}`

Get the current list of devices
GET`/device{?page_size,page_num,idsOnly}`

Get the current list of devices associated with given template
GET`/device/template/{template_id}{?page_size,page_num}`

Update device info
PUT`/device/{id}`

Configure device
PUT`/device/{deviceid}/actuate`

Delete device
DELETE`/device/{id}`