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

Device inventory filters and search

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:

  • 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 : docker.mender.io
BasePath : /api/management/v2/inventory
Schemes : HTTPS

Paths


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 :
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
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"
}

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

FilterPredicate

Attribute filter predicate

Name Description Schema
attribute
optional
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)
value
optional
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