Device inventory filters and search

reference

Overview

An API for inventory-based filters management and device search. It is 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 as scoped attributes.

This API enables the user to:

  • manage filters (list, create, read, delete)
  • search devices by inventory scoped attribute value
  • use the results to create and manage device groups for deployment scheduling

Version information

Version : 1

URI scheme

Host : hosted.mender.io
BasePath : /api/management/v2/inventory
Schemes : HTTPS

Paths


Create a new saved filter from a filter definition

POST /filters

Description

Creates a new saved filter from a filter definition.

Parameters

Type Name Description Schema
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string (Bearer [token])
Body body
optional
The definition of the filter body

body

Name Description Schema
name
optional
Name of the filter, must be unique. string
terms
optional
List of filter predicates, chained with boolean AND operators to build the search condition definition. < FilterPredicate > array

Responses

HTTP Code Description Schema
201 The filter was successfully created.
Headers :
Location (string) : URL of the newly created filter.
No Content
400 Missing or malformed request parameters. See error for details. Error
409 A filter with the same name already exists. Error
500 Internal error. Error

Consumes

  • application/json

Example HTTP response

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

List all the saved filters

GET /filters

Description

Returns a paged collection of saved filters and their definitions.

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 page
optional
Starting page. number (integer) 1
Query per_page
optional
Number of results per page. number (integer) 20

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'.
X-Total-Count (string) : Custom header indicating the total number of saved filters for the given query parameters.
< Filter > array
400 Missing or malformed request parameters. See error for details. Error
500 Internal error. Error

Example HTTP response

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

Search devices based on inventory attributes

POST /filters/search

Description

Returns a paged collection of devices and their attributes.

It accepts optional filters and sort parameters as body parameters.

Parameters

Type Name Description Schema
Header Authorization
required
Contains the JWT token issued by the User Administration and Authentication Service. string (Bearer [token])
Body body
optional
The search and sort parameters of the filter body

body

Name Description Schema
filters
optional
List of filter predicates, chained with boolean AND operators to build the search condition definition. < FilterPredicate > array
page
optional
Starting page. number (integer)
per_page
optional
Maximum number of results per page. number (integer)
sort
optional
List of ordered sort criterias < SortCriteria > array

Responses

HTTP Code Description Schema
200 Successful response.
Headers :
X-Total-Count (string) : Custom header indicating the total number of devices for the given query parameters.
< Device > array
400 Missing or malformed request parameters. See error for details. Error
500 Internal error. Error

Consumes

  • application/json

Example HTTP response

Response 200
[ {
  "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
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Return the definition of a saved filter

GET /filters/{id}

Description

Returns the definition of a saved filter from its unique identifier.

Parameters

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

Responses

HTTP Code Description Schema
200 Successful response. Filter
404 The filter was not found. ErrorNotFound
500 Internal error. Error

Example HTTP response

Response 200
{
  "id" : "myfilter",
  "name" : "My Filter",
  "terms" : [ {
    "scope" : "inventory",
    "attribute" : "serial_no",
    "type" : "$eq",
    "value" : "123456789"
  } ]
}
Response 404
{
  "error" : "filter not found",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Delete a saved filter

DELETE /filters/{id}

Description

Deletes a saved filter.

Parameters

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

Responses

HTTP Code Description Schema
204 The filter was successfully deleted. No Content
400 Missing or malformed request parameters. See error for details. Error
500 Internal error. Error

Consumes

  • application/json

Example HTTP response

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

Search devices using saved filter

GET /filters/{id}/search

Description

Returns a paged collection of devices and their 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
Filter identifier. string
Query page
optional
Starting page. number (integer) 1
Query per_page
optional
Number of results per page. number (integer) 20

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'.
X-Total-Count (string) : Custom header indicating the total number of devices for the given query parameters.
< Device > array
404 The filter was not found. ErrorNotFound
500 Internal error. Error

Example HTTP response

Response 200
[ {
  "id" : "291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e",
  "attributes" : [ {
    "name" : "ip_addr",
    "value" : "1.2.3.4",
    "scope" : "inventory",
    "description" : "IP address"
  }, {
    "name" : "mac_addr",
    "value" : "00:01:02:03:04:05",
    "scope" : "inventory",
    "description" : "MAC address"
  }, {
    "name" : "ports",
    "value" : [ "8080", "8081" ],
    "scope" : "system",
    "description" : "Open ports"
  } ],
  "updated_ts" : "2016-10-03T16:58:51.639Z"
}, {
  "id" : "76f40e5956c699e327489213df4459d1923e1a806603def19d417d004a4a3ef",
  "attributes" : [ {
    "name" : "mac",
    "value" : "00:01:02:03:04:05",
    "scope" : "inventory",
    "description" : "MAC address"
  } ],
  "updated_ts" : "2016-10-04T18:24:21.432Z"
} ]
Response 404
{
  "error" : "filter not found",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "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
scope
required
The scope of the attribute.

Scope is a string and acts as namespace for the attribute name.
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

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

ErrorNotFound

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

Filter

Filter definition

Name Description Schema
id
required
Unique identifier of the saved filter. string
name
required
Name of the saved filter. string
terms
optional
< FilterPredicate > array

FilterPredicate

Attribute filter predicate

Name Description Schema
attribute
required
Name of the attribute to be queried for filtering. string
scope
required
The scope of the attribute.

Scope is a string and acts as namespace for the attribute name.
string
type
required
Type or operator of the filter predicate. enum ($eq, $gt, $gte, $in, $lt, $lte, $ne, $nin, $exists)
value
required
The value of the attribute to be used in filtering.

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

SortCriteria

Sort criteria definition

Name Description Schema
attribute
required
Name of the attribute to be queried for filtering. string
order
required
Order direction, ascending or descending.

Defaults to ascending.
enum (asc, desc)
scope
required
The scope of the attribute.

Scope is a string and acts as namespace for the attribute name.
string

Found errors? Think you can improve this documentation? Simply click the Edit link at the top of the page, and then the icon on Github to submit changes.