WebSocket API Reference

The DeviceHive WebSocket API exposes the following services:

Client

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

After connection is established, clients need to authenticate using JSON Web Token, and then start sending commands to devices using the command/insert message. As soon as a command is processed by a device, the server sends the command/update message.

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.

Clients may also subscribe to device notifications using the notification/subscribe message and then start receiving server-originated messages about new device notifications.

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

WebSocket Handshake URI

GET /client
GET /device

Messages

MessageOriginatorAuthorizationDescription
authenticateClient/DeviceNoneAuthenticates a client by a JSON Web Token.
configuration/getClient/DeviceAccess JSON Web Token (ManageConfiguration)Returns requested property value.
configuration/putClient/DeviceAccess JSON Web Token (ManageConfiguration)Creates new or updates existing property.
configuration/deleteClient/DeviceAccess JSON Web Token (ManageConfiguration)Deletes a property.
command/getClient/DeviceAccess JSON Web Token (GetDeviceCommand)Gets information about the command.
command/listClient/DeviceAccess JSON Web Token (GetDeviceCommand)Gets the list of commands.
command/insertClient/DeviceAccess JSON Web Token (CreateDeviceCommand)Creates new device command.
command/subscribeClient/DeviceAccess JSON Web Token (GetDeviceCommand)Subscribes to device commands. After subscription is completed, the server will start to send command/insert messages to the connected user.
command/unsubscribeClient/DeviceAccess JSON Web Token (GetDeviceCommand)Unsubscribes from device commands.
command/updateClient/DeviceAccess JSON Web Token (UpdateDeviceCommand)Updates an existing device command on behalf of device.
device/getClient/DeviceAccess JSON Web Token (GetDevice)Gets information about the current device.
device/listClient/DeviceAccess JSON Web Token (GetDevice)Gets the list of devices.
device/saveClient/DeviceAccess JSON Web Token (RegisterDevice)Registers or updates a device.
device/deleteClient/DeviceAccess JSON Web Token (RegisterDevice)Deletes a device.
devicetype/listClient/DeviceAccess JSON Web Token (GetDeviceType)Gets list of device types. The result list is limited to device types the client has access to.
devicetype/countClient/DeviceAccess JSON Web Token (GetDeviceType)Gets count of device types the client has access to.
devicetype/getClient/DeviceAccess JSON Web Token (GetDeviceType)Gets information about device type and its devices.
devicetype/insertClient/DeviceAccess JSON Web Token (ManageDeviceType)Creates new device type.
devicetype/updateClient/DeviceAccess JSON Web Token (ManageDeviceType)Updates an existing device type.
devicetype/deleteClient/DeviceAccess JSON Web Token (ManageDeviceType)Deletes an existing device type.
network/listClient/DeviceAccess JSON Web Token (GetNetwork)Gets the list of networks.
network/getClient/DeviceAccess JSON Web Token (GetNetwork)Gets a network by ID.
network/insertClient/DeviceAccess JSON Web Token (ManageNetwork)Inserts new network.
network/updateClient/DeviceAccess JSON Web Token (ManageNetwork)Updates a network.
network/deleteClient/DeviceAccess JSON Web Token (ManageNetwork)Deletes a network by ID.
notification/getClient/DeviceAccess JSON Web Token (GetDeviceNotification)Gets information about the notification.
notification/listClient/DeviceAccess JSON Web Token (GetDeviceNotification)Gets the list of notifications.
notification/insertClient/DeviceAccess JSON Web Token (CreateDeviceNotification)Creates new device notification on behalf of device.
notification/subscribeClient/DeviceAccess JSON Web Token (GetDeviceNotification)Subscribes to device notifications. After subscription is completed, the server will start to send notification/insert messages to the connected user.
notification/unsubscribeClient/DeviceAccess JSON Web Token (GetDeviceNotification)Unsubscribes from device notifications.
subscription/listClient/DeviceAccess JSON Web Token (GetDeviceCommand or GetDeviceNotification)Returns list of user subscriptions.
server/infoClient/DeviceNoneGets meta-information about the current API.
tokenClient/DeviceNoneCreates access and refresh tokens by login and password.
token/createClient/DeviceAccess JSON Web Token (ManageToken)Creates access and refresh tokens by payload.
token/refreshClient/DeviceNoneRefreshes access token by refresh token.
srv: command/insertServern/aNotifies the user about new device command.
srv: command/updateServern/aNotifies the user about a command has been processed by a device. These messages are sent only for commands created by the current user within the current connection.
srv: notification/insertServern/aNotifies the user about new device notification.