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
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.