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.