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. |
Updated almost 5 years ago