Back to top

Device Management API

This document describes the APIs using the Device Manager 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,attr,attr_type,label,sortBy}

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&attr=foo=bar&attr_type=geopoint&label=dummy&sortBy=label
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: single (if data_attrs and config_attrs are to be omitted), split (if attrs list is to be omitted) or both. attrs field will always contain all template attributes that are listed by both data_attrs and config_attrs.

attr
string (optional) Example: foo=bar

Return only templates that possess a given attribute’s value.

attr_type
string (optional) Example: geopoint

Return only templates with attributes of a particular type.

label
string (optional) Example: dummy

Return only templates that are named accordingly (prefix or suffix match)

sortBy
string (optional) Example: label

Return entries sorted by given field. Currently only label is supported.

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"
        },
        {
          "created": "2018-02-27T16:10:23.178557+00:00",
          "label": "position",
          "value_type": "geopoint",
          "type": "dynamic",
          "id": 3,
          "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
        },
        {
          "created": "2018-02-27T16:10:23.178557+00:00",
          "label": "position",
          "value_type": "geopoint",
          "type": "dynamic",
          "id": 3,
          "template_id": "1"
        }
      ],
      "id": 1
    }
  ],
  "pagination": {
    "has_next": false,
    "next_page": null,
    "total": 1,
    "page": 1
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Page numbers must be greater than 1",
  "status": 400
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "At least one entry per page is mandatory",
  "status": 400
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "page_size and page_num must be integers",
  "status": 400
}

Delete all templates
DELETE/template

Removes all templates. If any device is based on the template being removed, an error message is returned.

Example URI

DELETE http://localhost:5000/template
Request
HideShow
Headers
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "removed": [
    {
      "attrs": [
        {
          "created": "2018-11-20T20:58:28.462464+00:00",
          "id": 182,
          "label": "position",
          "template_id": "4865",
          "type": "dynamic",
          "value_type": "geopoint"
        },
        {
          "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": "Templates cannot be removed as they are being used by devices",
  "status": 404
}

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 omitted) or “split” (if attrs list is to be omitted). 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/

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/
Request
HideShow
Headers
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "removed": {
    "attrs": [
      {
        "created": "2018-11-20T20:58:28.462464+00:00",
        "id": 182,
        "label": "position",
        "template_id": "4865",
        "type": "dynamic",
        "value_type": "geopoint"
      },
      {
        "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

Set to True if full device description is to be returned.

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
{
  "message": "If provided, count must be integer",
  "status": 400
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Verbose can only be used for single device creation",
  "status": 400
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Payload must be valid JSON, and Content-Type set accordingly",
  "status": 400
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": {
    "label": [
      "Missing data for required field."
    ]
  },
  "message": "failed to parse input"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": [
    "a device can not have repeated attributes"
  ],
  "status": 400
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "No such template: 1",
  "status": 404
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Failed to generate unique device_id",
  "status": 500
}

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
Headers
Content-Type: application/json
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,label,attr,attr_type,sortBy}

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 4865).

Example URI

GET http://localhost:5000/device?page_size=20&page_num=1&idsOnly=false&label=dummy&attr=foo=bar&attr_type=geopoint&sortBy=label
URI Parameters
HideShow
page_size
integer (optional) Example: 20
page_num
integer (optional) Example: 1
idsOnly
boolean (optional) Example: false

Return only the IDs of the devices (paginated).

attr
string (optional) Example: foo=bar

Return only devices that possess a given attribute’s value.

attr_type
string (optional) Example: geopoint

Return only devices with attributes of a particular type.

label
string (optional) Example: dummy

Return only devices that are named accordingly (prefix or suffix match).

sortBy
string (optional) Example: label

Return entries sorted by given field. Currently only label is supported.

Request  List complete device information
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"
]
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Page numbers must be greater than 1",
  "status": 400
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "At least one entry per page is mandatory",
  "status": 400
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "page_size and page_num must be integers",
  "status": 400
}

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": [
          {
            "created": "2018-11-20T20:58:29.564672+00:00",
            "id": 198,
            "label": "position",
            "template_id": "668",
            "type": "dynamic",
            "value_type": "geopoint"
          },
          {
            "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": "2019-05-13T18:42:01.633997+00:00",
            "id": 763,
            "label": "shared_key",
            "template_id": "189",
            "type": "static",
            "value_type": "psk"
          }
        ]
      },
      "created": "2017-12-20T18:15:08.864677+00:00",
      "id": "10cf",
      "label": "test_device",
      "templates": [
        "4865"
      ]
    }
  ],
  "pagination": {
    "has_next": false,
    "next_page": null,
    "page": 1,
    "total": 1
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Page numbers must be greater than 1",
  "status": 400
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "At least one entry per page is mandatory",
  "status": 400
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "page_size and page_num must be integers",
  "status": 400
}

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
{
  "message": "Payload must be valid JSON, and Content-Type set accordingly",
  "status": 400
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": {
    "label": [
      "Missing data for required field."
    ]
  },
  "message": "failed to parse input"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": [
    "a device can not have repeated attributes"
  ],
  "status": 400
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "No such device: aaaa",
  "status": 404
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "No such template: 4865",
  "status": 404
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Unknown template 4865 in attr list",
  "status": 400
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Unknown attribute 2 in override list",
  "status": 400
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Unknown metadata attribute 2 in override list",
  "status": 400
}

Configure device
PUT/device/{id}/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
id
string (required) Example: efac

Device ID being invoked.

Request
HideShow
Headers
Content-Type: application/json
Authorization: Bearer JWT
Body
{
  "attrs": {
    "battery": 10.6
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  " status": "configuration sent to device"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "No such device: aaaa",
  "status": 404
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "attrs": [
    "temperature"
  ],
  "status": "some of the attributes are not configurable"
}

Delete device
DELETE/device/

Removes a device.

Example URI

DELETE http://localhost:5000/device/
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
}

Delete all devices
DELETE/device

Delete all devices.

Example URI

DELETE http://localhost:5000/device
Request
HideShow
Headers
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "removed_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"
      ]
    }
  ],
  "result": "ok"
}

PSK Manipulation

Manipulates the devices’ keys.

Generate PSK
POST/device/gen_psk/{id}{?key_length,attrs}

Generates pre shared keys for a specific device.

This endpoint generates a random key to attributes with the type_value equal to psk. The generated key is returned just once, i.e, the user can not retrive it via /device.

Calling this endpoint twice with the same target attributes will override the previous one.

Example URI

POST http://localhost:5000/device/gen_psk/efac?key_length=8&attrs=shared_key
URI Parameters
HideShow
id
string (required) Example: efac

The device ID.

key_length
integer (required) Example: 8

Key’s length in bytes.

attrs
string (optional) Example: shared_key

Comma-separated list with the target attributes. If this parameter is not present the all aplicable attributes will be the target.

Request
HideShow
Headers
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "attribute": "shared_key",
    "psk": "9ee5c4eeca90b431"
  }
]
Response  204
HideShow
Headers
Content-Type: application/json
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "No such device: aaaa",
  "status": 404
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Missing key_length parameter",
  "status": 400
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "key_length must be greater than 0 and lesser than 1024",
  "status": 400
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not found some attributes, please check them",
  "status": 400
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Some attribute is not a 'psk' type_value",
  "status": 400
}

Copy PSK
PUT/device/{id}/attrs/{attr_label}/psk{?from_dev_id,from_attr_label}

Copies a generated pre-shared key from a device’s attribute to other device’s attribute.

This endpoint copies a previously generated pre-shared key from a device’s attribute to other.

The copied key does not is returned.

This endpoint does not create any link between the attributes, so if in a future the source attribute changes the key it will not reflect in others attributes previously copied from it.

Example URI

PUT http://localhost:5000/device/acaf/attrs/shared_key/psk?from_dev_id=efac&from_attr_label=shared_key
URI Parameters
HideShow
id
string (required) Example: acaf

The device where the destination attribute lives

attr_label
string (required) Example: shared_key

The destination attribute where the key is copied to

from_dev_id
string (required) Example: efac

The source device where the base attribute lives

from_attr_label
string (required) Example: shared_key

The source attribute where the key is copied from

Request
HideShow
Headers
Authorization: Bearer JWT
Response  204
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "No such device: 26e24a",
  "status": 404
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Not found attributes key",
  "status": 404
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Missing mandatory parameter: from_dev_id or/and from_attr_label",
  "status": 400
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Attribute key is not a 'psk' type_value",
  "status": 400
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "There is not a psk generated to key",
  "status": 400
}

Internal

Internal endpoints that can’t be accessed outside the platform. They are used for internal services’ intercommunication.

Device

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

Retrieves all information from a specific device.

Example URI

GET http://localhost:5000/internal/device/efac
URI Parameters
HideShow
id
string (required) Example: efac

Device id

Request
HideShow
Headers
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "templates": [
    "4865"
  ],
  "updated": "2018-04-09T19:41:33.648424+00:00",
  "attrs": {
    "4865": [
      {
        "type": "dynamic",
        "template_id": "4865",
        "id": 3,
        "label": "fan",
        "value_type": "bool",
        "created": "2018-04-09T19:35:41.336844+00:00"
      },
      {
        "created": "2018-04-09T19:35:41.334938+00:00",
        "value_type": "float",
        "id": 2,
        "label": "temperature",
        "template_id": "4865",
        "type": "dynamic"
      },
      {
        "template_id": "4865",
        "label": "shared_key",
        "id": 1,
        "created": "2018-04-09T19:35:41.329676+00:00",
        "value_type": "psk",
        "type": "static",
        "static_value": "64b5f380f4d140ff"
      }
    ]
  },
  "label": "secure_sensor",
  "id": "efac",
  "created": "2018-04-09T19:35:50.164960+00:00"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "No such device: aaaa",
  "status": 404
}

Get the current list of devices
GET/internal/device{?page_size,page_num,idsOnly,attr,label,sortBy}

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/internal/device?page_size=20&page_num=1&idsOnly=false&attr=foo=bar&label=dummy&sortBy=label
URI Parameters
HideShow
page_size
integer (optional) Example: 20
page_num
integer (optional) Example: 1
idsOnly
boolean (optional) Example: false

Return only the IDs of the devices (paginated).

attr
string (optional) Example: foo=bar

Return only devices that possess a given attribute’s value.

label
string (optional) Example: dummy

Return only devices that are named accordingly (prefix or suffix match).

sortBy
string (optional) Example: label

Return entries sorted by given field. Currently only label is supported.

Request  List complete device information
HideShow
Headers
Authorization: Bearer JWT
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "pagination": {
    "page": 1,
    "total": 1,
    "next_page": null,
    "has_next": false
  },
  "devices": [
    {
      "id": "206706",
      "templates": [
        "4865"
      ],
      "created": "2018-04-09T19:35:50.164960+00:00",
      "label": "secure_sensor",
      "updated": "2018-04-09T19:41:33.648424+00:00",
      "attrs": {
        "4865": [
          {
            "id": 3,
            "created": "2018-04-09T19:35:41.336844+00:00",
            "value_type": "bool",
            "template_id": "4865",
            "label": "fan",
            "type": "dynamic"
          },
          {
            "label": "temperature",
            "type": "dynamic",
            "template_id": "4865",
            "value_type": "float",
            "created": "2018-04-09T19:35:41.334938+00:00",
            "id": 2
          },
          {
            "value_type": "psk",
            "template_id": "4865",
            "type": "static",
            "label": "shared_key",
            "id": 1,
            "static_value": "64b5f380f4d140ff",
            "created": "2018-04-09T19:35:41.329676+00:00"
          }
        ]
      }
    }
  ]
}
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
[
  "206706",
  "204266",
  "58af00"
]
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Page numbers must be greater than 1",
  "status": 400
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "At least one entry per page is mandatory",
  "status": 400
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "page_size and page_num must be integers",
  "status": 400
}

Generated by aglio on 07 Mar 2022