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.

MethodAuthorizationUriDescription
loginNonePOST /tokenCreates and returns access and refresh tokens for the given user.
createAccess JSON Web Token (ManageToken)POST /token/createCreates and returns access and refresh tokens for the given user and access rights.
refreshNonePOST /token/refreshCreates 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.

MethodAuthorizationUriDescription
getNoneGET /infoGets meta-information of the current API.
getClusterNoneGET /info/config/clusterReturns information about cluster (Kafka, Zookeeper etc.)

Configuration

Represents a configuration property.

For Configuration resource details, see the resource representation page.

MethodAuthorizationUriDescription
getJSON Web Token (ManageConfiguration)GET /configuration/{name}Returns requested property value.
putJSON Web Token (ManageConfiguration)PUT /configuration/{name}Creates new or updates existing property.
deleteJSON 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.

MethodAuthorizationUriDescription
listAccess JSON Web Token (GetDevice)GET /deviceGets list of devices.
getAccess JSON Web Token (GetDevice)GET /device/{id}Gets information about device.
registerAccess JSON Web Token (RegisterDevice)PUT /device/{id}Registers or updates a device. For initial device registration, only 'name' property is required.
deleteAccess 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.

listAccess JSON Web Token (GetDeviceType)GET /devicetypeGets list of device types.
The result list is limited to device types the client has access to.
countAccess JSON Web Token (GetDeviceType)GET /devicetype/countGets count of device types the client has access to.
getAccess JSON Web Token (GetDeviceType)GET /devicetype/{id}Gets information about device type and its devices.
insertAccess JSON Web Token (ManageDeviceType)POST /devicetypeCreates new device type.
updateAccess JSON Web Token (ManageDeviceType)PUT /devicetype/{id}Updates an existing device type.
deleteAccess 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.

MethodAuthorizationUriDescription
queryAccess JSON Web Token (GetDeviceCommand)GET /device/{deviceId}/commandQueries device commands.
getAccess JSON Web Token (GetDeviceCommand)GET /device/{deviceId}/command/{commandId}Gets information about device command.
insertAccess JSON Web Token (CreateDeviceCommand)POST /device/{deviceId}/commandCreates new device command.
updateAccess JSON Web Token (GetDeviceCommand)GET /device/{deviceId}/command/pollUpdates an existing device command.
pollAccess JSON Web Token (GetDeviceCommand)GET /device/{deviceId}/command/{commandId}/pollPolls 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.
waitAccess JSON Web Token (GetDeviceCommand)GET /device/{deviceId}/command/{commandId}/pollWaits 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.
pollManyAccess JSON Web Token (GetDeviceCommand)GET /device/command/pollPolls 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.

MethodAuthorizationUriDescription
queryAccess JSON Web Token (GetDeviceNotification)GET /device/{deviceId}/notificationQueries device notifications.
getAccess JSON Web Token (GetDeviceNotification)GET /device/{deviceId}/notification/{id}Gets information about device notification.
insertAccess JSON Web Token (CreateDeviceNotification)POST /device/{deviceId}/notificationCreates new device notification.
pollAccess JSON Web Token (GetDeviceNotification)GET /device/{deviceId}/notification/pollPolls 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.
pollManyAccess JSON Web Token (GetDeviceNotification)GET /device/notification/pollPolls 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.

MethodAuthorizationUriDescription
listAccess JSON Web Token (GetNetwork)GET /networkGets list of device networks.
The result list is limited to networks the client has access to.
getAccess JSON Web Token (GetNetwork)GET /network/{id}Gets information about device network and its devices.
insertAccess JSON Web Token (ManageNetwork)POST /networkCreates new device network.
updateAccess JSON Web Token (ManageNetwork)PUT /network/{id}Updates an existing device network.
deleteAccess 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.

MethodAuthorizationUriDescription
listAccess JSON Web Token (ManageUser)GET /userGets list of users.
getAccess 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.
insertAccess JSON Web Token (ManageUser)POST /userCreates new user.
updateAccess 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.
deleteAccess JSON Web Token (ManageUser)DELETE /user/{id}Deletes an existing user.
getCurrentAccess JSON Web Token (ManageUser)GET /user/currentGets information about user/network association.
Only administrators are allowed to get information about any user. User-level accounts can only retrieve information about themselves.
updateCurrentAccess JSON Web Token (ManageUser)PUT /user/currentUpdates 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.
getNetworkAccess JSON Web Token (ManageUser)GET /user/{id}/network/{networkId}Gets information about user/network association.
assignNetworkAccess JSON Web Token (ManageUser)PUT /user/{id}/network/{networkId}Associates network with the user.
unassignNetworkAccess JSON Web Token (ManageUser)DELETE /user/{id}/network/{networkId}Removes association between network and user.