Sensor Groups are used to logically organize related sensors. A Sensors can be a member of many groups.
Currently, all Sensor Groups have public visibility, but only the owner (creator) can add/remove sensors from the group.
Sensor Groups can be manipulated using a REST API in the following section
All request body and response bodies use JSON. The following fields are present:
Field Name | Type | Required | Notes |
---|---|---|---|
id | Integer | true | The id contains a unique number which is used to identify the group |
name | String[4,50] | true | The name is a system-unique string identifier for the group. Names must be lowercase containing alphanumeric, underscores or hyphens [a-z0-9_-]. The first character must be an alphabetic character |
longName | String[,255] | optional | A readable name used for visual interfaces. |
owner | String[4,50] | true | The name of the group’s owner. This field is set by the system and cannot be modified. |
description | String[,255] | optional | A simple description of the group |
imageUrl | String[,255] | optional | A string url to an image which can be used to represent this group |
sensors | Array[Sensor] | optional | Contains a JSON list of sensors. This field is only useful for viewing sensors. To append/remove sensors from Sensor Groups, refer to Adding a Sensor to Sensor Group. |
An example of a Sensor Group JSON would be follows:
{
id: 49,
name: "water-sensor",
longName: "A water sensor",
owner: "robertl",
description: "This is a short description",
imageUrl: "http://someurl.com/water-sensor.jpg"
sensors: []
}
Provides a list of groups on the system as an array using the JSON format specified in Sensor Group Format
URL | http://wotkit.sensetecnic.com/api/groups/ |
Method | GET |
Returns | OK 200, along with list |
example
curl --user {id}:{password} --request GET 'http://wotkit.sensetecnic.com/api/groups'
Similar to listing a group, but retrieving only a single sensor. Replace {group-name} with group.id or group.name. The API accepts both formats
URL | http://wotkit.sensetecnic.com/api/groups/{group-name} |
Method | GET |
Returns | OK 200 |
example
curl --user {id}:{password} --request GET 'http://wotkit.sensetecnic.com/api/groups'
To create a sensor group, append the Sensor Group contents following Sensor Group Format.
On creation, the id and owner fields are ignored because they are system generated.
URL | http://wotkit.sensetecnic.com/api/groups |
Method | POST |
Returns | If a sensor with the same name exists, ERROR 409. Otherwise, OK 204. |
Modifying is similar to creation, the content is placed in the response body
Again, the id and owner fields in the JSON object are ignored if they are modified. The Sensor Group is specified by substituting {group-name} in the URL with either group.id or group.name. The API accepts both formats.
URL | http://wotkit.sensetecnic.com/api/groups/{group-name} |
Method | PUT |
Returns | If user has no permissions to edit group, returns UNAUTHORIZED 401, otherwise OK 204 |
Deleting a Sensor Group is fairly trivial, assuming you are the owner of the group. A request body is unnecessary.
URL | http://wotkit.sensetecnic.com/api/groups/{group-name} |
Method | DELETE |
Returns | If user has no permissions to edit group, returns UNAUTHORIZED 401, otherwise OK 204 |
This is done by invoking the URL by replacing the specified parameters where {group-name} can be group.id or group.name. {sensor-id} should be sensor.id.
URL | http://wotkit.sensetecnic.com/api/groups/{group-name}/sensors/{sensor-id} |
Method | POST |
The response will contain one of the following response codes.
Return Code | Description |
---|---|
OK 204 | No Content is given. |
400 | Sensor is already a member of sensor group |
401 | User is unauthorized to edit group. |
The format is the same as Adding a Sensor to Sensor Group except replacing method with DELETE
URL | http://wotkit.sensetecnic.com/api/groups/{group-name}/sensors/{sensor-id} |
Method | DELETE |
The response will contain one of the following codes.
Return Code | Description |
---|---|
OK 204 | No Content is given. If a sensor does not exist in a group, this is also returned. |
401 | User is unauthorized to edit group |