Back to top

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

Register a new 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
}

Generated by aglio on 08 May 2020