Device Connectivity Made Easy

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

Get Started

REST API Reference

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

None

POST /token

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

Access JSON Web Token (ManageToken)

POST /token/create

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

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

None

GET /info

Gets meta-information of the current API.

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

JSON Web Token (ManageConfiguration)

GET /configuration/{name}

Returns requested property value.

JSON Web Token (ManageConfiguration)

PUT /configuration/{name}

Creates new or updates existing property.

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

Access JSON Web Token (GetDevice)

GET /device

Gets list of devices.

Access JSON Web Token (GetDevice)

GET /device/{id}

Gets information about device.

Access JSON Web Token (RegisterDevice)

PUT /device/{id}

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

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.

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.

Access JSON Web Token (GetDeviceType)

GET /devicetype/count

Gets count of device types the client has access to.

Access JSON Web Token (GetDeviceType)

GET /devicetype/{id}

Gets information about device type and its devices.

Access JSON Web Token (ManageDeviceType)

POST /devicetype

Creates new device type.

Access JSON Web Token (ManageDeviceType)

PUT /devicetype/{id}

Updates an existing device type.

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

Access JSON Web Token (GetDeviceCommand)

GET /device/{deviceId}/command

Queries device commands.

Access JSON Web Token (GetDeviceCommand)

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

Gets information about device command.

Access JSON Web Token (CreateDeviceCommand)

POST /device/{deviceId}/command

Creates new device command.

Access JSON Web Token (GetDeviceCommand)

GET /device/{deviceId}/command/poll

Updates an existing device command.

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.

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.

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

Access JSON Web Token (GetDeviceNotification)

GET /device/{deviceId}/notification

Queries device notifications.

Access JSON Web Token (GetDeviceNotification)

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

Gets information about device notification.

Access JSON Web Token (CreateDeviceNotification)

POST /device/{deviceId}/notification

Creates new device notification.

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.

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

Access JSON Web Token (GetNetwork)

GET /network

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

Access JSON Web Token (GetNetwork)

GET /network/{id}

Gets information about device network and its devices.

Access JSON Web Token (ManageNetwork)

POST /network

Creates new device network.

Access JSON Web Token (ManageNetwork)

PUT /network/{id}

Updates an existing device network.

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

Access JSON Web Token (ManageUser)

GET /user

Gets list of users.

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.

Access JSON Web Token (ManageUser)

POST /user

Creates new user.

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.

Access JSON Web Token (ManageUser)

DELETE /user/{id}

Deletes an existing user.

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.

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.

Access JSON Web Token (ManageUser)

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

Gets information about user/network association.

Access JSON Web Token (ManageUser)

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

Associates network with the user.

Access JSON Web Token (ManageUser)

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

Removes association between network and user.