Skip to content

How to use

Jump to bottom
Anton Medviediev edited this page May 5, 2017 · 49 revisions

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

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 value
id (integer, optional)
login (string)
passwordHash (string, optional)
passwordSalt (string, optional)
loginAttempts (integer, optional)
role (string, optional) = ['ADMIN', 'CLIENT']
status (string, optional) = ['ACTIVE', 'LOCKED_OUT', 'DISABLED', 'DELETED']
lastLogin (string, optional)
googleLogin (string, optional)
facebookLogin (string, optional)
githubLogin (string, optional)
data (JsonStringWrapper, optional)
admin (boolean, optional)

Create user

POST /user
Description

Creates new user.

Parameters
Type Name Description Schema
Body body
required 		User body UserUpdate
Responses
HTTP Code Description Schema
201 If successful, this method returns a User resource in the response body. UserVO
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. < UserVO > 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. UserVO
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 UserUpdate
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. UserVO
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 UserUpdate
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. NetworkVO
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 NetworkVO
Responses
HTTP Code Description Schema
201 If successful, this method returns a Network resource in the response body. NetworkVO
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. < NetworkVO > 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. NetworkVO
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 NetworkUpdate
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 unit that runs microcode.

Method Authorization Uri
list GetDevice GET /device
get GetDevice GET /device/{id}
register RegisterDevice PUT /device/{id}
delete RegisterDevice DELETE /device/{id}
equipment GetDeviceState GET /device/{id}/equipment
equipmentByCode GetDeviceState GET /device/{id}/equipment/{code}

Resource Representation

name value
id (integer, optional)
guid (string, optional)
name (string, optional)
data (JsonStringWrapper, optional)
network (NetworkVO, optional)
deviceClass (DeviceClassVO, optional)
isBlocked (boolean, optional)

List devices

GET /device
Description

Gets list of devices.

Parameters
Type Name Description Schema Default
Query deviceClassId
optional 		Filter by associated device class identifier. integer (int64)
Query deviceClassName
optional 		Filter by associated device class name. 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, DeviceClass)
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
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' and 'deviceClass' properties are required.

Parameters
Type Name Description Schema
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
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

Get device's equipment

GET /device/{id}/equipment
Description

Gets current state of device equipment. The equipment state is tracked by framework and it could be updated by sending 'equipment' notification with the following parameters: equipment: equipment code parameters: current equipment state

Parameters
Type Name Description Schema
Path id
required 		Device unique identifier. string
Responses
HTTP Code Description Schema
200 If successful, this method returns an array of DeviceEquipment resources in the response body. < DeviceEquipmentVO > array
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

Get current state of equipment

GET /device/{id}/equipment/{code}
Description

Gets current state of device equipment by code.

Parameters
Type Name Description Schema
Path code
required 		Equipment code. string
Path id
required 		Device unique identifier. string
Responses
HTTP Code Description Schema
200 If successful, this method returns a DeviceEquipment resource in the response body. DeviceEquipmentVO
401 If request is not authorized No Content
403 If principal doesn't have permissions No Content
404 If device or equipment is not found. No Content
Consumes
  • application/json
Produces
  • application/json

Device Class

Represents an entity that holds all meta-information about particular type of devices.

Method Authorization Uri
list ManageDeviceClass GET /device/class
get GetDevice GET /device/class/{id}
insert ManageDeviceClass POST /device/class
update ManageDeviceClass PUT /device/class/{id}
delete ManageDeviceClass DELETE /device/class/{id}

Resource Representation

name value
id (integer, optional)
name (string)
isPermanent (boolean, optional)
data (JsonStringWrapper, optional)
entityVersion (integer, optional)
equipment (Array[DeviceClassEquipmentVO], optional)

Create device class

POST /device/class
Description

Creates new device class.

Parameters
Type Name Description Schema
Body body
required 		Device class body DeviceClassWithEquipmentVO
Responses
HTTP Code Description Schema
201 If successful, this method returns a DeviceClass resource in the response body. DeviceClassWithEquipmentVO
400 If request is malformed No Content
401 If request is not authorized No Content
403 If principal doesn't have permissions or device class with same name exists. No Content
Consumes
  • application/json
Produces
  • application/json

List device classes

GET /device/class
Description

Gets list of device classes.

Parameters
Type Name Description Schema Default
Query name
optional 		Filter by device class name. string
Query namePattern
optional 		Filter by device class 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 DeviceClass resources in the response body. < DeviceClassWithEquipmentVO > 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

Create equipment

POST /device/class/{deviceClassId}/equipment
Description

Creates equipment

Parameters
Type Name Description Schema
Path deviceClassId
required 		Device class {id} integer (int64)
Body body
required 		Equipment body DeviceClassEquipmentVO
Responses
HTTP Code Description Schema
201 Equipment successfully created DeviceClassEquipmentVO
400 Invalid request parameters No Content
403 Duplicate equipment entry with code = {code} for device class with id :{id} No Content
404 Device Class with current id Not Found No Content
Consumes
  • application/json

Get equipment

GET /device/class/{deviceClassId}/equipment/{id}
Description

Returns equipment by device class id and equipment id

Parameters
Type Name Description Schema
Path deviceClassId
required 		Device class id integer (int64)
Path id
required 		Equipment id integer (int64)
Responses
HTTP Code Description Schema
200 Equipment was found DeviceClassEquipmentVO
404 If equipment not found No Content

Update equipment

PUT /device/class/{deviceClassId}/equipment/{id}
Description

Updates equipment. Returns empty body if equipment updated.

Parameters
Type Name Description Schema
Path deviceClassId
required 		Device class id integer (int64)
Path id
required 		Equipment id integer (int64)
Body body
required 		Equipment body EquipmentUpdate
Responses
HTTP Code Description Schema
204 Equipment successfully updated No Content
404 If equipment not found No Content
Consumes
  • application/json

Delete equipment

DELETE /device/class/{deviceClassId}/equipment/{id}
Description

Deletes equipment

Parameters
Type Name Description Schema
Path deviceClassId
required 		Device class id integer (int64)
Path id
required 		Equipment id integer (int64)
Responses
HTTP Code Description Schema
204 Equipment successfully deleted No Content
404 If equipment not found No Content
Consumes
  • application/json

Get device class

GET /device/class/{id}
Description

Gets information about device class and its equipment.

Parameters
Type Name Description Schema
Path id
required 		Device class identifier. integer (int64)
Responses
HTTP Code Description Schema
200 If successful, this method returns a DeviceClass resource in the response body. DeviceClassWithEquipmentVO
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 class not found No Content
Consumes
  • application/json
Produces
  • application/json

Update device class

PUT /device/class/{id}
Description

Updates an existing device class.

Parameters
Type Name Description Schema
Path id
required 		Device class identifier. integer (int64)
Body body
required 		Device class body DeviceClassUpdate
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 class is not found No Content
Consumes
  • application/json
Produces
  • application/json

Update device class

DELETE /device/class/{id}
Description

Deletes an existing device class.

Parameters
Type Name Description Schema
Path id
required 		Device class 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

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

Device Notification

Method Authorization Uri Description
query GetDeviceNotification GET /device/{deviceGuid}/notification Returns notifications by provided parameters.
get GetDeviceNotification GET /device/{deviceGuid}/notification/{id} Returns notification by device guid and notification id
insert CreateDeviceNotification POST /device/{deviceGuid}/notification Creates new device notification.
poll GetDeviceNotification GET /device/{deviceGuid}/notification/poll Polls new notifications for specific device. This method returns all device notifications that were created after specified timestamp.
pollMany GetDeviceNotification GET /device/notification/poll Polls new device notifications. This method returns all device notifications that were created after specified timestamp.

Device Command

Method Authorization Uri Description
query GetDeviceCommand GET /device/{deviceGuid}/command Queries device commands.
get GetDeviceCommand GET /device/{deviceGuid}/command/{id} Gets information about device command.
insert CreateDeviceCommand POST /device/{deviceGuid}/command Creates new device command.
update UpdateDeviceCommand PUT /device/{deviceGuid}/command/{id} Updates an existing device command.
poll GetDeviceCommand GET /device/{deviceGuid}/command/poll Returns all device commands that were created after specified timestamp for specific device.
wait GetDeviceCommand GET /device/{deviceGuid}/command/{id}/poll Wait for a command to be processed
pollMany GetDeviceCommand GET /device/command/poll Polls new device commands.

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.
Clone this wiki locally