You are browsing documentation for a version other than the latest stable release. Switch to the latest stable release, 1.1.

Device inventory

Overview

An API for device attribute management and device grouping. Intended for use by the web GUI.

Devices can upload vendor-specific attributes (software/hardware info, health checks, metrics, etc.) of various data types to the backend.

This API enables the user to:

  • list devices with their attributes
  • search devices by attribute value
  • use the results to create and manage device groups for the purpose of deployment scheduling

Version information

Version : 1

URI scheme

Host : docker.mender.io
BasePath : /api/management/v1/inventory
Schemes : HTTPS

Paths


Create a device resource with the supplied set of attributes

POST /devices

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Body device
required
DeviceNew

Responses

HTTP Code Description Schema
201 The device was successfully created.
Headers :
Location (string) : URI for the newly created 'Device' resource.
No Content
400 Malformed request body. See error for details. Error
409 Conflict - the device already exists. Error
500 Internal server error. Error

Example HTTP request

Request body
json :
{
  "application/json" : {
    "id" : "291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e",
    "attributes" : [ {
      "name" : "ip_addr",
      "value" : "1.2.3.4",
      "description" : "IP address"
    }, {
      "name" : "mac_addr",
      "value" : "00.01:02:03:04:05",
      "description" : "MAC address"
    }, {
      "name" : "ports",
      "value" : [ "8080", "8081" ],
      "description" : "Open ports"
    } ]
  }
}

Example HTTP response

Response 400
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 409
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

List devices

GET /devices

Description

Returns a paged collection of devices and their attributes. Accepts optional search and sort parameters.

Searching Searching by attributes values is accomplished by appending attribute name/value pairs to the query string, e.g.:

GET /devices?attr_name_1=foo&
             attr_name_2=100&
             ...

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Query has_group
optional
If present, limits the results only to devices assigned/not assigned to a group. boolean
Query page
optional
Starting page. number(integer) "1"
Query per_page
optional
Number of results per page. number(integer) "10"
Query sort
optional
Supports sorting the device list by attribute values.

The parameter is formatted as a list of attribute names and sort directions, e.g.:

'?sort=attr1:asc, attr2:desc'

will sort by 'attr1' ascending, and then by 'attr2' descending. 'desc' is the default
sort direction, and can be omitted.
string

Responses

HTTP Code Description Schema
200 Successful response.
Headers :
Link (string) : Standard header, used for page navigation.

Supported relation types are 'first', 'next' and 'prev'.
< Device > array
400 Missing or malformed request parameters. See error for details. Error
500 Internal error. Error

Example HTTP response

Response 200
json :
{
  "application/json" : [ {
    "id" : "291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e",
    "attributes" : [ {
      "name" : "ip_addr",
      "value" : "1.2.3.4",
      "description" : "IP address"
    }, {
      "name" : "mac_addr",
      "value" : "00.01:02:03:04:05",
      "description" : "MAC address"
    }, {
      "name" : "ports",
      "value" : [ "8080", "8081" ],
      "description" : "Open ports"
    } ],
    "updated_ts" : "2016-10-03T16:58:51.639Z"
  }, {
    "id" : "76f40e5956c699e327489213df4459d1923e1a806603def19d417d004a4a3ef",
    "attributes" : [ {
      "name" : "mac",
      "value" : "00:01:02:03:04:05",
      "description" : "MAC address"
    } ],
    "updated_ts" : "2016-10-04T18:24:21.432Z"
  } ]
}
Response 400
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Get a selected device

GET /devices/{id}

Description

Returns the details of the selected devices, including its attributes.

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path id
required
Device identifier. string

Responses

HTTP Code Description Schema
200 Successful response - the device was found. Device
404 The device was not found. Error
500 Internal server error. Error

Example HTTP response

Response 200
json :
{
  "application/json" : {
    "id" : "291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e",
    "attributes" : [ {
      "name" : "ip_addr",
      "value" : "1.2.3.4",
      "description" : "IP address"
    }, {
      "name" : "mac_addr",
      "value" : "00.01:02:03:04:05",
      "description" : "MAC address"
    }, {
      "name" : "ports",
      "value" : [ "8080", "8081" ],
      "description" : "Open ports"
    } ],
    "updated_ts" : "2016-10-03T16:58:51.639Z"
  }
}
Response 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Remove selected device

DELETE /devices/{id}

Description

Deletes all information concerning the device, including its attributes.

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path id
required
Device identifier. string

Responses

HTTP Code Description Schema
204 Device removed No Content
500 Internal server error. Error

Example HTTP response

Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Get a selected device's group

GET /devices/{id}/group

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path id
required
Device identifier. string

Responses

HTTP Code Description Schema
200 Successful response.

If the device is not assigned to any group, the 'group' field will be set to 'null'.
Group
400 Missing or malformed request params or body. See the error message for details. No Content
404 The device was not found. Error
500 Internal server error. Error

Example HTTP response

Response 200
json :
{
  "application/json" : {
    "group" : "testing"
  }
}
Response 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Add a device to a group

PUT /devices/{id}/group

Description

Adds a device to a group.

Note that a given device can belong to at most one group. If a device already belongs to some group, it will be moved to the selected one.

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path id
required
Device identifier. string
Body group
required
Group descriptor. Group

Responses

HTTP Code Description Schema
204 Success - the device was added to the group. No Content
404 The device was not found. Error
500 Internal server error. Error

Example HTTP request

Request body
json :
{
  "application/json" : {
    "group" : "staging"
  }
}

Example HTTP response

Response 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Remove a device from a group

DELETE /devices/{id}/group/{name}

Description

Removes the device with identifier 'id' from the group 'group'.

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path id
required
Device identifier. string
Path name
required
Group name. string

Responses

HTTP Code Description Schema
204 The device was successfully removed from the group. No Content
404 The device was not found or doesn't belong to the group. Error
500 Internal error. Error

Example HTTP response

Response 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

List groups

GET /groups

Description

Returns a collection of all defined device groups.

Responses

HTTP Code Description Schema
200 Successful response. < string > array
500 Internal server error. Error

Example HTTP response

Response 200
json :
{
  "application/json" : [ "staging", "testing", "production" ]
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

List the devices belonging to a given group

GET /groups/{name}/devices

Description

Returns a paged collection of device IDs.

Parameters

Type Name Description Schema Default
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string(Bearer [token])
Path name
required
Group name. string
Query page
optional
Starting page. number(integer) "1"
Query per_page
optional
Number of results per page. number(integer) "10"

Responses

HTTP Code Description Schema
200 Successful response
Headers :
Link (string) : Standard header, we support 'first', 'next', and 'prev'.
< string > array
400 Invalid request parameters. Error
404 The group was not found. Error
500 Internal server error. Error

Example HTTP response

Response 400
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 404
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}
Response 500
json :
{
  "application/json" : {
    "error" : "failed to decode device group data: JSON payload is empty",
    "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
  }
}

Definitions

Attribute

Attribute descriptor.

Name Description Schema
description
optional
Attribute description. string
name
required
A human readable, unique attribute ID, e.g. 'device_type', 'ip_addr', 'cpu_load', etc. string
value
required
The current value of the attribute.

Attribute type is implicit, inferred from the JSON type.

Supported types: number, string, array of numbers, array of strings. Mixed arrays are not allowed.
string

Device

Name Description Schema
attributes
optional
A list of attribute descriptors. < Attribute > array
id
optional
Mender-assigned unique ID. string
updated_ts
optional
Timestamp of the most recent attribute update. string

DeviceNew

Name Description Schema
attributes
optional
A list of attribute descriptors. < Attribute > array
id
required
Mender-assigned unique ID. string
updated_ts
optional
Timestamp of the most recent attribute update. string

Error

Error descriptor.

Name Description Schema
error
optional
Description of the error. string
request_id
optional
Request ID (same as in X-MEN-RequestID header). string

Group

Device group.

Name Description Schema
group
required
string