How to use

The DeviceHive Server is the central part of the framework which allows different components to interact with each other. The API provides access to information about registered components in the system, and allows them to exchange messages in real time.

Contents

• Metadata
  • User
    • Resource Representation
    • Create user
    • List users
    • Get current user
    • Update current user
    • Get user
    • Update user
    • Delete user
    • Get user's network
    • Assign network
    • Unassign network
  • Network
    • Resource Representation
    • Create network
    • List networks
    • Get network
    • Update network
    • Delete network
  • Device
    • Resource Representation
    • List devices
    • Get device
    • Register device
    • Delete device
    • Get device's equipment
    • Get current state of equipment
  • JwtToken
    • Resource Representation
    • JwtPayload
    • JwtRequest
    • JwtToken
    • Login
    • JWT access and refresh token request
    • JWT access token request with refresh token
• Operational Data
  • REST
  • DeviceCommand
    • Poll for commands.
    • Create new device command.
    • Query commands.
    • Poll for commands.
    • Get command
    • Update an existing device command.
    • Wait for a command to be processed.
  • DeviceNotification
    • Poll for notifications
    • Create notification
    • Get notifications
    • Poll for notifications
    • Get notification
  • Websockets
    • Device: authenticate
    • Device: command/subscribe
    • Device: command/unsubscribe
    • Device: command/update
    • Device: device/get
    • Device: device/list
    • Device: device/save
    • Device: notification/insert

Metadata

DeviceHive Metadata is the information about users, networks of devices, and the specific devices within these networks. This data can be accessed and modified via the REST api.

User

Represents a user with credentials and API access rights (client or administrator). Administrators automatically have all possible API access rights.

Method	Authorization	Uri
list	ManageUser	GET /user
get	GetCurrentUser	GET /user/{id}
insert	ManageUser	POST /user
update	UpdateCurrentUser	PUT /user/{id}
delete	ManageUser	DELETE /user/{id}
getCurrent	GetCurrentUser	GET /user/current
updateCurrentUser	UpdateCurrentUser	PUT /user/current
getNetwork	ManageUser	GET /user/{id}/network/{networkId}
assignNetwork	ManageUser	PUT /user/{id}/network/{networkId}
unassignNetwork	ManageUser	DELETE /user/{id}/network/{networkId}

Resource Representation

Name	Description	Schema
admin optional	Default : false	boolean
data optional		JsonStringWrapper
id optional		integer (int64)
lastLogin optional		string (date-time)
login required	Length : 1 - 128	string
loginAttempts optional		integer (int32)
passwordHash optional		string
passwordSalt optional		string
role optional		enum (ADMIN, CLIENT)
status optional		enum (ACTIVE, LOCKED_OUT, DISABLED, DELETED)

Create user

POST /user

Description

Creates new user.

Parameters

Type	Name	Description	Schema
Body	body required	User body	User

Responses

HTTP Code	Description	Schema
201	If successful, this method returns a User resource in the response body.	User
400	If request is malformed	No Content
401	If request is not authorized	No Content
403	If principal doesn't have permissions	No Content

Consumes

• application/json

Produces

• application/json

List users

GET /user

Description

Gets list of users.

Parameters

Type	Name	Description	Schema	Default
Query	login optional	Filter by user login.	string
Query	loginPattern optional	Filter by user login pattern.	string
Query	role optional	Filter by user role. 0 is Administrator, 1 is Client.	integer (int32)
Query	skip optional	Number of records to skip from the result list.	integer (int32)	0
Query	sortField optional	Result list sort field.	enum (ID, Login)
Query	sortOrder optional	Result list sort order. Available values are ASC and DESC.	enum (ASC, DESC)
Query	status optional	Filter by user status. 0 is Active, 1 is Locked Out, 2 is Disabled.	integer (int32)
Query	take optional	Number of records to take from the result list.	integer (int32)	20

Responses

HTTP Code	Description	Schema
200	If successful, this method returns array of User resources in the response body.	< User > array
400	If request parameters invalid	No Content
401	If request is not authorized	No Content
403	If principal doesn't have permissions	No Content

Consumes

• application/json

Produces

• application/json

Get current user

GET /user/current

Description

Get information about the current user.

Responses

HTTP Code	Description	Schema
200	If successful, this method returns a User resource in the response body.	User
401	If request is not authorized	No Content
403	If principal doesn't have permissions	No Content
409	If user is not signed in	No Content

Consumes

• application/json

Produces

• application/json

Update current user

PUT /user/current

Description

Updates an existing user. Only administrators are allowed to update any property of any user. User-level accounts can only change their own password in case:

1. They already have a password.
2. They provide a valid current password in the 'oldPassword' property.

Parameters

Type	Name	Description	Schema
Body	body required	User body	User

Responses

HTTP Code	Description	Schema
204	If successful, this method returns an empty response body.	No Content
400	If request is malformed	No Content
401	If request is not authorized	No Content
403	If principal doesn't have permissions	No Content

Consumes

• application/json

Produces

• application/json

Get user

GET /user/{id}

Description

Gets information about user and its assigned networks. Only administrators are allowed to get information about any user. User-level accounts can only retrieve information about themselves.

Parameters

Type	Name	Description	Schema
Path	id required	User identifier.	integer (int64)

Responses

HTTP Code	Description	Schema
200	If successful, this method returns a User resource in the response body.	User
400	If request is malformed	No Content
401	If request is not authorized	No Content
403	If principal doesn't have permissions	No Content
404	If user is not found	No Content

Consumes

• application/json

Produces

• application/json

Update user

PUT /user/{id}

Parameters

Type	Name	Description	Schema
Path	id required	User identifier.	integer (int64)
Body	body required	User body	User

Responses

HTTP Code	Description	Schema
404	If user not found	No Content

Consumes

• application/json

Produces

• application/json

Delete user

DELETE /user/{id}

Description

Deletes an existing user.

Parameters

Type	Name	Description	Schema
Path	id required	User identifier.	integer (int64)

Responses

HTTP Code	Description	Schema
204	If successful, this method returns an empty response body.	No Content
401	If request is not authorized	No Content
403	If principal doesn't have permissions	No Content
404	If access key is not found	No Content

Consumes

• application/json

Produces

• application/json

Get user's network

GET /user/{id}/network/{networkId}

Description

Gets information about user/network association.

Parameters

Type	Name	Description	Schema
Path	id required	User identifier.	integer (int64)
Path	networkId required	Network identifier.	integer (int64)

Responses

HTTP Code	Description	Schema
200	If successful, this method returns a Network resource in the response body.	Network
401	If request is not authorized	No Content
403	If principal doesn't have permissions	No Content
404	If user or network not found	No Content

Consumes

• application/json

Produces

• application/json

Assign network

PUT /user/{id}/network/{networkId}

Description

Associates network with the user.

Parameters

Type	Name	Description	Schema
Path	id required	User identifier.	integer (int64)
Path	networkId required	Network identifier.	integer (int64)

Responses

HTTP Code	Description	Schema
204	If successful, this method returns an empty response body.	No Content
401	If request is not authorized	No Content
403	If principal doesn't have permissions	No Content
404	If user or network not found	No Content

Consumes

• application/json

Produces

• application/json

Unassign network

DELETE /user/{id}/network/{networkId}

Description

Removes association between network and user.

Parameters

Type	Name	Description	Schema
Path	id required	User identifier.	integer (int64)
Path	networkId required	Network identifier.	integer (int64)

Responses

HTTP Code	Description	Schema
204	If successful, this method returns an empty response body.	No Content
401	If request is not authorized	No Content
403	If principal doesn't have permissions	No Content
404	If user or network not found.	No Content

Consumes

• application/json

Produces

• application/json

Network

Represents an isolation entity that encapsulates multiple devices with controlled access.

Method	Authorization	Uri
list	GetNetwork	GET /network
get	GetNetwork	GET /network/{id}
insert	ManageNetwork	POST /network
update	ManageNetwork	PUT /network/{id}
delete	ManageNetwork	DELETE /network/{id}

Resource Representation

name	value
id	(integer, optional)
key	(string, optional)
name	(string)
description	(string, optional)
entityVersion	(integer, optional)

Create network

POST /network

Description

Creates new device network.

Parameters

Type	Name	Description	Schema
Body	body required	Network body	Network

Responses

HTTP Code	Description	Schema
201	If successful, this method returns a Network resource in the response body.	Network
400	If request is malformed	No Content
401	If request is not authorized	No Content
403	If principal doesn't have permissions	No Content

Consumes

• application/json

List networks

GET /network

Description

Gets list of device networks the client has access to.

Parameters

Type	Name	Description	Schema	Default
Query	name optional	Filter by network name.	string
Query	namePattern optional	Filter by network name pattern.	string
Query	skip optional	Number of records to skip from the result list.	integer (int32)	0
Query	sortField optional	Result list sort field.	enum (ID, Name)
Query	sortOrder optional	Result list sort order.	enum (ASC, DESC)
Query	take optional	Number of records to take from the result list.	integer (int32)	20

Responses

HTTP Code	Description	Schema
200	If successful, this method returns array of Network resources in the response body.	< Network > array
400	If request parameters invalid	No Content
401	If request is not authorized	No Content
403	If principal doesn't have permissions	No Content

Consumes

• application/json

Get network

GET /network/{id}

Description

Gets information about device network and its devices.

Parameters

Type	Name	Description	Schema
Path	id required	Network identifier.	integer (int64)

Responses

HTTP Code	Description	Schema
200	If successful, this method returns a Network resource in the response body.	Network
400	If request is malformed	No Content
401	If request is not authorized	No Content
403	If principal doesn't have permissions	No Content
404	If network not found	No Content

Consumes

• application/json

Update network

PUT /network/{id}

Description

Updates an existing device network.

Parameters

Type	Name	Description	Schema
Path	id required	Network identifier.	integer (int64)
Body	body required	Network body	Network

Responses

HTTP Code	Description	Schema
204	If successful, this method returns an empty response body.	No Content
400	If request is malformed	No Content
401	If request is not authorized	No Content
403	If principal doesn't have permissions	No Content

Consumes

• application/json

Delete network

DELETE /network/{id}

Description

Deletes an existing device network.

Parameters

Type	Name	Description	Schema
Path	id required	Network identifier.	integer (int64)

Responses

HTTP Code	Description	Schema
204	If successful, this method returns an empty response body.	No Content
401	If request is not authorized	No Content
403	If principal doesn't have permissions	No Content
404	If network not found	No Content

Consumes

• application/json

Device

Represents a device, a unit that runs microcode and communicates to this API.

Resource Representation

Name	Description	Schema
data optional		JsonStringWrapper
deviceId optional		string
id optional		integer (int64)
isBlocked optional	Default : false	boolean
name required	Length : 1 - 128	string
networkId optional		integer (int64)

List devices

GET /device

Description

Gets list of devices.

Parameters

Type	Name	Description	Schema	Default
Header	Authorization required	Authorization token	string
Query	name optional	Filter by device name.	string
Query	namePattern optional	Filter by device name pattern.	string
Query	networkId optional	Filter by associated network identifier.	integer (int64)
Query	networkName optional	Filter by associated network name.	string
Query	skip optional	Number of records to skip from the result list.	integer (int32)	0
Query	sortField optional	Result list sort field.	enum (Name, Status, Network)
Query	sortOrder optional	Result list sort order.	enum (ASC, DESC)
Query	take optional	Number of records to take from the result list.	integer (int32)	20

Responses

HTTP Code	Description	Schema
200	If successful, this method returns array of Device resources in the response body.	< DeviceVO > array
400	If request parameters invalid	No Content
401	If request is not authorized	No Content
403	If principal doesn't have permissions	No Content

Consumes

• application/json

Produces

• application/json

Get device

GET /device/{id}

Description

Gets information about device.

Parameters

Type	Name	Description	Schema
Header	Authorization required	Authorization token	string
Path	id required	Device unique identifier.	string

Responses

HTTP Code	Description	Schema
200	If successful, this method returns a Device resource in the response body.	No Content
400	If request is malformed	No Content
401	If request is not authorized	No Content
403	If principal doesn't have permissions	No Content
404	If device is not found	No Content

Consumes

• application/json

Produces

• application/json

Register device

PUT /device/{id}

Description

Registers or updates a device. For initial device registration, only 'name' property is required.

Parameters

Type	Name	Description	Schema
Header	Authorization required	Authorization token	string
Path	id required	Device unique identifier.	string
Body	body required	Device body	DeviceUpdate

Responses

HTTP Code	Description	Schema
204	If successful, this method returns an empty response body.	No Content
400	If request is malformed	No Content
401	If request is not authorized	No Content
403	If principal doesn't have permissions	No Content

Consumes

• application/json

Produces

• application/json

Delete device

DELETE /device/{id}

Description

Deletes an existing device.

Parameters

Type	Name	Description	Schema
Header	Authorization required	Authorization token	string
Path	id required	Device unique identifier.	string

Responses

HTTP Code	Description	Schema
204	If successful, this method returns an empty response body.	No Content
400	If request is malformed	No Content
401	If request is not authorized	No Content
403	If principal doesn't have permissions	No Content
404	If device is not found	No Content

Consumes

• application/json

Produces

• application/json

Operational Data

Operational data is created in real time and translated between devices and servers. It is required for the proper functioning of the IoT network. Operational data consists of Notifications and Commands.

Notifications are units of information dispatched from devices.

Commands are sent to devices and typically mean some command that is to be executed by the device.

REST

DeviceCommand

Polls the server to get commands.

GET /device/command/poll

Description

This method returns all device commands that were created after specified timestamp. In the case when no commands were found, the method blocks until new command is received. If no commands are received within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call with the same timestamp value.

Parameters

Type	Name	Description	Schema	Default
Query	deviceGuids optional	List of device GUIDs	string
Query	limit optional	Limit number of commands	integer (int32)	100
Query	names optional	Command names	string
Query	timestamp optional	Timestamp to start from	string
Query	waitTimeout optional	Wait timeout in seconds	integer (int64)	30

Responses

HTTP Code	Description	Schema
200	successful operation	< DeviceCommand > array

Consumes

• application/json

Creates new device command.

POST /device/{deviceGuid}/command

Description

Creates new device command, stores and returns command with generated id.

Parameters

Type	Name	Description	Schema
Path	deviceGuid required	Device GUID	string
Body	body required	Command body	DeviceCommand

Responses

HTTP Code	Description	Schema
200	successful operation	DeviceCommand
404	If device not found	No Content

Consumes

• application/json

Query commands.

GET /device/{deviceGuid}/command

Description

Gets list of commands that has been received in specified time range.

Parameters

Type	Name	Description	Schema	Default
Path	deviceGuid required	Device GUID	string
Query	command optional	Command name	string
Query	end optional	End timestamp	string
Query	skip optional	Skip param	integer (int32)	0
Query	sortField optional	Sort field	string	"timestamp"
Query	sortOrder optional	Sort order	string
Query	start optional	Start timestamp	string
Query	status optional	Command status	string
Query	take optional	Limit param	integer (int32)	100

Responses

HTTP Code	Description	Schema
200	successful operation	< DeviceCommand > array

Consumes

• application/json

Polls the server to get commands.

GET /device/{deviceGuid}/command/poll

Description

This method returns all device commands that were created after specified timestamp. In the case when no commands were found, the method blocks until new command is received. If no commands are received within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call with the same timestamp value.

Parameters

Type	Name	Description	Schema	Default
Path	deviceGuid required	Device GUID	string
Query	limit optional	Limit number of commands	integer (int32)	100
Query	names optional	Command names	string
Query	timestamp optional	Timestamp to start from	string
Query	waitTimeout optional	Wait timeout in seconds	integer (int64)	30

Responses

HTTP Code	Description	Schema
200	successful operation	< DeviceCommand > array

Consumes

• application/json

Get command

GET /device/{deviceGuid}/command/{commandId}

Description

Gets command by device GUID and command id

Parameters

Type	Name	Description	Schema
Path	commandId required	Command Id	string
Path	deviceGuid required	Device GUID	string

Responses

HTTP Code	Description	Schema
200	successful operation	DeviceCommand
404	If device or command not found	No Content

Consumes

• application/json

Updates an existing device command.

PUT /device/{deviceGuid}/command/{commandId}

Description

Updates an existing device command.

Parameters

Type	Name	Description	Schema
Path	commandId required	Command Id	integer (int64)
Path	deviceGuid required	Device GUID	string
Body	body required	Command body	DeviceCommand

Responses

HTTP Code	Description	Schema
200	successful operation	DeviceCommand
404	If device or command not found	No Content

Consumes

• application/json

Waits for a command to be processed.

GET /device/{deviceGuid}/command/{commandId}/poll

Description

Waits for a command to be processed.

This method returns a command only if it has been processed by a device.

In the case when command is not processed, the method blocks until device acknowledges command execution. If the command is not processed within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call.

Parameters

Type	Name	Description	Schema	Default
Path	commandId required	Command Id	string
Path	deviceGuid required	Device GUID	string
Query	waitTimeout optional	Wait timeout in seconds (default: 30 seconds, maximum: 60 seconds). Specify 0 to disable waiting.	integer (int64)	30

Responses

HTTP Code	Description	Schema
200	successful operation	DeviceCommand
204	Command was not processed during waitTimeout.	No Content
400	Command with commandId was not sent for device with deviceGuid or wrong input parameters.	No Content
404	Device or command was not found.	No Content

Consumes

• application/json

DeviceNotification

Poll for notifications

GET /device/notification/poll

Description

Polls new device notifications.

This method returns all device notifications that were created after specified timestamp.

In the case when no notifications were found, the method blocks until new notification is received. If no notifications are received within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call with the same timestamp value.

Parameters

Type	Name	Description	Schema	Default
Query	deviceGuids optional	Device guids	string
Query	names optional	Notification names	string
Query	timestamp optional	Timestamp to start from	string
Query	waitTimeout optional	Wait timeout	integer (int64)	30

Responses

HTTP Code	Description	Schema
200	OK	< DeviceNotification > array

Create notification

POST /device/{deviceGuid}/notification

Description

Creates notification

Parameters

Type	Name	Description	Schema
Path	deviceGuid required	Device GUID	string
Body	body required	Notification body	DeviceNotification

Responses

HTTP Code	Description	Schema
201	notification sent	DeviceNotification
400	If request is malformed	No Content
403	If device is not connected to network	No Content
404	If device not found	No Content

Consumes

• application/json

Get notifications

GET /device/{deviceGuid}/notification

Description

Returns notifications by provided parameters

Parameters

Type	Name	Description	Schema	Default
Path	deviceGuid required	Device GUID	string
Query	end optional	End timestamp	string
Query	notification optional	Notification name	string
Query	skip optional	Skip param	integer (int32)	0
Query	sortField optional	Sort field	string	"timestamp"
Query	sortOrder optional	Sort order	string
Query	start optional	Start timestamp	string
Query	take optional	Limit param	integer (int32)	100

Responses

HTTP Code	Description	Schema
200	successful operation	DeviceNotification

Poll for notifications

GET /device/{deviceGuid}/notification/poll

Description

Polls new device notifications for specified device Guid.

This method returns all device notifications that were created after specified timestamp.

In the case when no notifications were found, the method blocks until new notification is received. If no notifications are received within the waitTimeout period, the server returns an empty response. In this case, to continue polling, the client should repeat the call with the same timestamp value.

Parameters

Type	Name	Description	Schema	Default
Path	deviceGuid required	Device GUID	string
Query	names optional	Notification names	string
Query	timestamp optional	Timestamp to start from	string
Query	waitTimeout optional	Wait timeout	integer (int64)	30

Responses

HTTP Code	Description	Schema
200	OK	< DeviceNotification > array

Get notification

GET /device/{deviceGuid}/notification/{id}

Description

Returns notification by device guid and notification id

Parameters

Type	Name	Description	Schema
Path	deviceGuid required	Device GUID	string
Path	id required	Notification id	integer (int64)

Responses

HTTP Code	Description	Schema
200	Returned notification by device guid and notification id	DeviceNotification
404	If device or notification not found	No Content

Websockets

The service allows devices to exchange messages with the DeviceHive server using a single persistent connection.

After connection is established, devices need to register using the device/save message, perform authentication and then start sending notifications using the notification/insert message.

Devices may also subscribe to commands using the command/subscribe message and then start receiving server-originated messages about new commands.

Message	Originator	Authorization	Description
authenticate	Device	None	Authenticates a device. After successful authentication, all subsequent messages may exclude deviceId and deviceKey parameters.
command/subscribe	Device	Device	Subscribes the device to commands. After subscription is completed, the server will start to send command/insert messages to the connected device.
command/unsubscribe	Device	Device	Unsubscribes the device from commands.
command/update	Device	Device	Updates an existing device command.
device/get	Device	Device	Gets information about the current device.
device/save	Device	Device	Registers or updates a device.
notification/insert	Device	Device	Creates new device notification.
server/info	Device	None	Gets meta-information of the current API.
srv: command/insert	Server	n/a	Notifies the device about new command.

Device: authenticate

Authenticates a device. After successful authentication, all subsequent messages may exclude JSON Web Token parameter.

Request Message

Authorization

None

Message Representation

{
    "action": {string},
    "requestId": {object},
    "token": {string}
}

Message Parameters

Property Name	Required	Type	Description
action	Yes	string	Action name: authenticate
requestId	No	object	Request unique identifier, will be passed back in the response message.
token	Yes	string	Access JSON Web Token.

Server Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object}
}

Message Parameters

Property Name	Type	Description
action	string	Action name: authenticate
status	string	Operation execution status (success or error).
requestId	object	Request unique identifier as specified in the request message.

Device: command/subscribe

Subscribes the device to commands. After subscription is completed, the server will start to send command/insert messages to the connected device.

Request Message

Authorization

Device

Message Representation

{
    "action": {string},
    "requestId": {object},
    "token": {string},
    "timestamp": {datetime}
}

Message Parameters

Property Name	Required	Type	Description
action	Yes	string	Action name: command/subscribe
requestId	No	object	Request unique identifier, will be passed back in the response message.
token	No	string	Access JSON Web Token (specify if not authenticated).
timestamp	No	datetime	Timestamp of the last received command (UTC). If not specified, the server’s timestamp is taken instead.

Server Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object}
}

Message Parameters

Property Name	Type	Description
action	string	Action name: command/subscribe
status	string	Operation execution status (success or error).
requestId	object	Request unique identifier as specified in the request message.

Device: command/unsubscribe

Unsubscribes the device from commands.

Request Message

Authorization

Device

Message Representation

{
    "action": {string},
    "requestId": {object},
    "token": {string},
}

Message Parameters

Property Name	Required	Type	Description
action	Yes	string	Action name: command/unsubscribe
requestId	No	object	Request unique identifier, will be passed back in the response message.
token	No	string	Access JSON Web Token (specify if not authenticated).

Server Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object}
}

Message Parameters

Property Name	Type	Description
action	string	Action name: command/unsubscribe
status	string	Operation execution status (success or error).
requestId	object	Request unique identifier as specified in the request message.

Device: command/update

Updates an existing device command.

Request Message

Authorization

Device

Message Representation

{
    "action": {string},
    "requestId": {object},
    "token": {string},
    "commandId": {integer},
    "command": {
        "command": {string},
        "parameters": {object},
        "lifetime": {integer},
        "status": {string},
        "result": {object}
    }
}

Message Parameters

Property Name	Required	Type	Description
action	Yes	string	Action name: command/update
requestId	No	object	Request unique identifier, will be passed back in the response message.
token	No	string	Access JSON Web Token (specify if not authenticated).
commandId	Yes	integer	Device command identifier.
command	Yes	object	A [DeviceCommand][] resource to update.
command.command	No	string	Command name.
command.parameters	No	object	Command parameters, a JSON object with an arbitrary structure.
command.lifetime	No	integer	Command lifetime, a number of seconds until this command expires.
command.status	No	string	Command status, as reported by device or related infrastructure.
command.result	No	object	Command execution result, an optional value that could be provided by device.

Server Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object}
}

Message Parameters

Property Name	Type	Description
action	string	Action name: command/update
status	string	Operation execution status (success or error).
requestId	object	Request unique identifier as specified in the request message.

Device: device/get

Gets information about the current device.

Request Message

Authorization

Device

Message Representation

{
    "action": {string},
    "requestId": {object},
    "token": {string},
}

Message Parameters

Property Name	Required	Type	Description
action	Yes	string	Action name: device/get
requestId	No	object	Request unique identifier, will be passed back in the response message.
token	No	string	Access JSON Web Token (specify if not authenticated).

Server Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object},
    "device": {
        "id": {string},
        "name": {string},
        "status": {string},
        "data": {object},
        "network": {
            "id": {integer},
            "name": {string},
            "description": {string}
        }
    }
}

Message Parameters

Property Name	Type	Description
action	string	Action name: device/get
status	string	Operation execution status (success or error).
requestId	object	Request unique identifier as specified in the request message.
device	object	The [Device][] resource representing the current device.
device.id	string	Device unique identifier.
device.name	string	Device display name.
device.status	string	Device operation status. The status is optional and it can be set to an arbitrary value, if applicable.
device.data	object	Device data, a JSON object with an arbitrary structure.
device.network	object	Associated network object.
device.network.id	integer	Network identifier.
device.network.name	string	Network display name.
device.network.description	string	Network description.

Device: device/list

Gets the list of devices.

Request Message

Authorization

Device

Message Representation

{
    "action": {string},
    "requestId": {object},
    "token": {string}
}

Message Parameters

Property Name	Required	Type	Description
action	Yes	string	Action name: device/list
requestId	No	object	Request unique identifier, will be passed back in the response message.
token	No	string	Access JSON Web Token (specify if not authenticated).

Server Message

Message Representation

{
    "action": {string},
    "requestId": {object},
    "status": {string},
    "devices": [{
        "id": {string},
        "name": {string},
        "status": {string},
        "data": {object},
        "networkId": {integer},
        "isBlocked": {boolean}
    }]
}

Message Parameters

Property Name	Type	Description
action	string	Action name: device/get
requestId	object	Request unique identifier as specified in the request message.
status	string	Operation execution status (success or error).
devices	array	The array of Devices.
device	object	The [Device][] resource representing the user device.
device.id	string	Device unique identifier.
device.name	string	Device display name.
device.status	string	Device operation status. The status is optional and it can be set to an arbitrary value, if applicable.
device.data	object	Device data, a JSON object with an arbitrary structure.
device.networkId	integer	Network identifier.
device.isBlocked	boolean	Device isBlocked identifier.

Device: device/save

Registers or updates a device.

Request Message

Authorization

Device

Message Representation

{
    "action": {string},
    "requestId": {object},
    "token": {string},
    "deviceId": {string},
    "device": {
        "id": {string},
        "name": {string},
        "data": {object},
        "networkId": {integer},
        "isBlocked": {boolean}
    }
}

Message Parameters

Property Name	Required	Type	Description
action	Yes	string	Action name: device/save
requestId	No	object	Request unique identifier, will be passed back in the response message.
token	Yes	string	Access JSON Web Token (specify if not authenticated).
deviceId	No	string	Device unique identifier (specify if not authenticated).
device	Yes	object	A [Device][] resource to register or update.
device.id	No	string	Device unique identifier.
device.name	No	string	Device display name.
device.data	No	object	Device data, a JSON object with an arbitrary structure.
device.networkId	No	integer	Associated network id.
device.isBlocked	No	boolean	Indicates whether device is blocked.

Server Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object}
}

Message Parameters

Property Name	Type	Description
action	string	Action name: device/save
status	string	Operation execution status (success or error).
requestId	object	Request unique identifier as specified in the request message.

Device: notification/insert

Creates new device notification.

Request Message

Authorization

Device

Message Representation

{
    "action": {string},
    "requestId": {object},
    "token": {string},
    "notification": {
        "notification": {string},
        "parameters": {object}
    }
}

Message Parameters

Property Name	Required	Type	Description
action	Yes	string	Action name: notification/insert
requestId	No	object	Request unique identifier, will be passed back in the response message.
token	No	string	Access JSON Web Token (specify if not authenticated).
notification	Yes	object	A [DeviceNotification][] resource to create.
notification.notification	Yes	string	Notification name.
notification.parameters	No	object	Notification parameters, a JSON object with an arbitrary structure.

Server Message

Message Representation

{
    "action": {string},
    "status": {string},
    "requestId": {object},
    "notification": {
        "id": {integer},
        "timestamp": {datetime}
    }
}

Message Parameters

Property Name	Type	Description
action	string	Action name: notification/insert
status	string	Operation execution status (success or error).
requestId	object	Request unique identifier as specified in the request message.
notification	object	An inserted [DeviceNotification][] resource.
notification.id	integer	Notification identifier.
notification.timestamp	datetime	Notification timestamp (UTC).