DeviceHive

Device Connectivity Made Easy

Focus on your product and innovation and leave communication and management to DeviceHive.

Get Started

REST API Reference

Suggest Edits

The DeviceHive REST API exposes the following resources:

Authentication

Provides a mechanism of authentication to this API.

For Authentication resource details, see the resource representation page.

Method
Authorization
Uri
Description

login

None

POST /token

Creates and returns access and refresh tokens for the given user.

create

Access JSON Web Token (ManageToken)

POST /token/create

Creates and returns access and refresh tokens for the given user and access rights.

refresh

None

POST /token/refresh

Creates and returns a new access token for the given refresh token.

ApiInfo

Represents meta-information about the current API.

For ApiInfo resource details, see the resource representation page.

Method
Authorization
Uri
Description

get

None

GET /info

Gets meta-information of the current API.

getCluster

None

GET /info/config/cluster

Returns information about cluster (Kafka, Zookeeper etc.)

Configuration

Represents a configuration property.

For Configuration resource details, see the resource representation page.

Method
Authorization
Uri
Description

get

JSON Web Token (ManageConfiguration)

GET /configuration/{name}

Returns requested property value.

put

JSON Web Token (ManageConfiguration)

PUT /configuration/{name}

Creates new or updates existing property.

delete

JSON Web Token (ManageConfiguration)

DELETE /configuration/{name}

Deletes a property.

Device

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

For Device resource details, see the resource representation page.

Method
Authorization
Uri
Description

list

Access JSON Web Token (GetDevice)

GET /device

Gets list of devices.

get

Access JSON Web Token (GetDevice)

GET /device/{id}

Gets information about device.

register

Access JSON Web Token (RegisterDevice)

PUT /device/{id}

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

delete

Access JSON Web Token (RegisterDevice)

DELETE /device/{id}

Deletes an existing device.

DeviceType

Represents a type of the device.

For DeviceType resource details, see the resource representation page.

list

Access JSON Web Token (GetDeviceType)

GET /devicetype

Gets list of device types.
The result list is limited to device types the client has access to.

count

Access JSON Web Token (GetDeviceType)

GET /devicetype/count

Gets count of device types the client has access to.

get

Access JSON Web Token (GetDeviceType)

GET /devicetype/{id}

Gets information about device type and its devices.

insert

Access JSON Web Token (ManageDeviceType)

POST /devicetype

Creates new device type.

update

Access JSON Web Token (ManageDeviceType)

PUT /devicetype/{id}

Updates an existing device type.

delete

Access JSON Web Token (ManageDeviceType)

DELETE /devicetype/{id}

Deletes an existing device type.

DeviceCommand

Represents a device command, a unit of information sent to devices.

For DeviceCommand resource details, see the resource representation page.

Method
Authorization
Uri
Description

query

Access JSON Web Token (GetDeviceCommand)

GET /device/{deviceId}/command

Queries device commands.

get

Access JSON Web Token (GetDeviceCommand)

GET /device/{deviceId}/command/{commandId}

Gets information about device command.

insert

Access JSON Web Token (CreateDeviceCommand)

POST /device/{deviceId}/command

Creates new device command.

update

Access JSON Web Token (GetDeviceCommand)

GET /device/{deviceId}/command/poll

Updates an existing device command.

poll

Access JSON Web Token (GetDeviceCommand)

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

Polls new device commands.
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.

wait

Access JSON Web Token (GetDeviceCommand)

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

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.

pollMany

Access JSON Web Token (GetDeviceCommand)

GET /device/command/poll

Polls new device commands.
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.

DeviceNotification

Represents a device notification, a unit of information dispatched from devices.

For DeviceNotification resource details, see the resource representation page.

Method
Authorization
Uri
Description

query

Access JSON Web Token (GetDeviceNotification)

GET /device/{deviceId}/notification

Queries device notifications.

get

Access JSON Web Token (GetDeviceNotification)

GET /device/{deviceId}/notification/{id}

Gets information about device notification.

insert

Access JSON Web Token (CreateDeviceNotification)

POST /device/{deviceId}/notification

Creates new device notification.

poll

Access JSON Web Token (GetDeviceNotification)

GET /device/{deviceId}/notification/poll

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.

pollMany

Access JSON Web Token (GetDeviceNotification)

GET /device/notification/poll

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.

Network

Represents a network, an isolated area where devices reside.

For Network resource details, see the resource representation page.

Method
Authorization
Uri
Description

list

Access JSON Web Token (GetNetwork)

GET /network

Gets list of device networks.
The result list is limited to networks the client has access to.

get

Access JSON Web Token (GetNetwork)

GET /network/{id}

Gets information about device network and its devices.

insert

Access JSON Web Token (ManageNetwork)

POST /network

Creates new device network.

update

Access JSON Web Token (ManageNetwork)

PUT /network/{id}

Updates an existing device network.

delete

Access JSON Web Token (ManageNetwork)

DELETE /network/{id}

Deletes an existing device network.

User

Represents a user to this API.

For User resource details, see the resource representation page.

Method
Authorization
Uri
Description

list

Access JSON Web Token (ManageUser)

GET /user

Gets list of users.

get

Access JSON Web Token (GetCurrentUser)

GET /user/{id}

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.

insert

Access JSON Web Token (ManageUser)

POST /user

Creates new user.

update

Access JSON Web Token (UpdateCurrentUser)

PUT /user/{id}

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:

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

delete

Access JSON Web Token (ManageUser)

DELETE /user/{id}

Deletes an existing user.

getCurrent

Access JSON Web Token (ManageUser)

GET /user/current

Gets information about user/network association.
Only administrators are allowed to get information about any user. User-level accounts can only retrieve information about themselves.

updateCurrent

Access JSON Web Token (ManageUser)

PUT /user/current

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

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

getNetwork

Access JSON Web Token (ManageUser)

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

Gets information about user/network association.

assignNetwork

Access JSON Web Token (ManageUser)

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

Associates network with the user.

unassignNetwork

Access JSON Web Token (ManageUser)

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

Removes association between network and user.