2.10. Sensor Groups¶
Sensor Groups are used to logically organize related sensors. Any sensor can be a member of many groups.
Currently, all Sensor Groups have private visibility, and only the owner (creator) can add/remove sensors from the group, or make a group public.
Sensor Groups can be manipulated using a REST API in the following section
2.10.1. Sensor Group Format¶
All request body and response bodies use JSON. The following fields are present:
Field Name | Type | Notes | |
---|---|---|---|
(REQUIRED) | id | Integer | The id contains a unique number which is used to identify the group |
(REQUIRED) | name | String[4,50] | 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 |
(REQUIRED) | longName | String[4,100] | A readable name used for visual interfaces. It must be at least 4 characters long. |
(READ-ONLY) | owner | String[4,50] | The name of the group’s owner. This field is set by the system and cannot be modified. |
(REQUIRED) | description | String[,255] | A simple description of the group |
(OPTIONAL) | imageUrl | String[,255] | A string url to an image which can be used to represent this group |
(OPTIONAL) | sensors | Array[Sensor] | 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 as follows:
{
"id": 602,
"name": "test",
"longName": "test",
"description": "test",
"tags": [
"group",
"test"
],
"imageUrl": "",
"latitude": 49.25,
"longitude": -123.1,
"visibility": "PUBLIC",
"owner": "sensetecnic",
"lastUpdate": "1970-01-01T00:00:00.000Z",
"created": "2014-03-27T23:29:51.479Z",
"metadata": {
"meta": "data"
},
"childCount": 0,
"things": [],
"thingType": "GROUP"
}
2.10.2. List Groups¶
Provides a list of all PUBLIC groups on the system as an array using the JSON format specified in Sensor Group Format
URL | http://wotkit.sensetecnic.com/api/v1/groups/ |
Privacy | Public or Private |
Format | json |
Method | GET |
Returns | 200 OK if successul. A JSON object in the response body containing a list of groups. |
example
curl --user {id}:{password} --request GET 'http://wotkit.sensetecnic.com/api/v1/groups'
2.10.3. Viewing a Single Sensor Group¶
Similar to List Groups, but will retrieve only a single sensor group. Replace {group-name}
with the group’s {id}
integer or {owner}.{name}
string. The API accepts both formats
URL | http://wotkit.sensetecnic.com/api/v1/groups/{group-name} |
Privacy | Public or Private |
Format | json |
Method | GET |
Returns | 200 OK if successful. A JSON object in the response body describing the sensor group. |
example
curl --user {id}:{password} --request GET 'http://wotkit.sensetecnic.com/api/v1/groups/sensetecnic.test'
2.10.4. Creating a Sensor Group¶
To create a sensor group, append the Sensor Group contents following Sensor Group Format.
On creation, the id is ignored because it is system generated. You should not provide an owner as it will be generated by the system to match the credentials used to call the API. Only if you are an administrator user you will be able to provide an owner.
URL | http://wotkit.sensetecnic.com/api/v1/groups |
Privacy | Private |
Format | json |
Method | POST |
Returns | 201 Created if successful; 409 Conflict if a sensor with the same name exists. |
2.10.5. Modifying Sensor Group Fields¶
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}
group’s {id}
integer or {owner}.{name}
string. The API accepts both formats.
URL | http://wotkit.sensetecnic.com/api/v1/groups/{group-name} |
Privacy | Private |
Format | json |
Method | PUT |
Returns | 204 No Content if successful; 401 Unauthorized if user has no permissions to edit group. |
2.10.6. Deleting a Sensor Group¶
Deleting a Sensor Group is fairly trivial, assuming you are the owner of the group. A response body is unnecessary.
URL | http://wotkit.sensetecnic.com/api/v1/groups/{group-name} |
Privacy | Private |
Format | json |
Method | DELETE |
Returns | 204 No Content if successful; 401 Unauthorized if user has no permissions to edit group. |
2.10.7. Adding a Sensor to Sensor Group¶
This is done by invoking the URL by replacing the specified parameters where
{group-name}
can be the group’s {id}
integer or {owner}.{name}
string. {sensor-id}
should
be the sensor’s id
integer.
URL | http://wotkit.sensetecnic.com/api/v1/groups/{group-name}/sensors/{sensor-id} |
Privacy | Private |
Format | json |
Method | POST |
Returns | 204 No Content if successful; 400 if sensor is already a member of sensor group; 401 Unauthorized if user is unauthorized to edit group. |
2.10.8. Removing a Sensor from Sensor Group¶
The format is the same as Adding a Sensor to Sensor Group except replacing method
with DELETE
. Replace {sensor-id}
with the sensor’s {id}
integer.
URL | http://wotkit.sensetecnic.com/api/v1/groups/{group-name}/sensors/{sensor-id} |
Privacy | Private |
Format | n/a |
Method | DELETE |
Returns | 204 No Content if successful; 401 Unauthorized if user is unauthorized to edit group. |