Thing Groups API
The Thing Groups REST API is used to manage thing groups.
CREATE
Required role: ReadWrite
Required privilege: ThingGroups.CREATE on the specified domain
Required privilege: ThingGroups.READ on the specified domain
Creates a new thing group.
A group may be a child group of another group, if so, they have to share the same domain.
API Endpoint: [POST]
: /thing-groups
Request
Headers
Authorization
: The Authorization token returned from/auth/login
x-api-key
: The API Key to identify the request
Body
domain
: The id of the domain that the thing group should belong to. requireddescription
: A description of the thing group. requiredparent
: The id of another group. optional
Example body
{
"domain": "root",
"description": "My group",
"parent": "another-thing-group-id"
}
Response
id
: The id of the thing group.description
: The description.domain
: The domain.createdAt
: A UNIX timestamp indicating the moment of creation.parent
: The id of the parent group, if applicable. optional
Errors
Key | Params | Property | Description |
---|---|---|---|
NOT_AUTHORIZED |
Returned if the user is not authorized for the operation. | ||
PROPERTY_REQUIRED |
Returned if a required parameter is missing. | ||
INVALID_ARGUMENTS |
Returned if a parameter does not fulfil requirements. | ||
NOT_AUTHORIZED_DOMAIN |
domain |
Returned if the domain does not exist. | |
THING_GROUP_NOT_FOUND |
parent |
Returned if the parent group does not exist. |
UPDATE
Required role: ReadWrite
Required privilege: ThingGroups.UPDATE on thedomain
of the specified Thing Group
Required privilege: ThingGroups.READ on thedomain
of the specified Thing Group
Update a thing group.
API Endpoint: [PATCH]
: /thing-groups/{id}
Request
Headers
Authorization
: The Authorization token returned from/auth/login
x-api-key
: The API Key to identify the request
Path
id
: The id of the thing group. required
Body
description
: A description of the thing group. required
Example body
{
"description": "My updated description"
}
Response
id
: The id of the thing group.description
: The description.domain
: The domain.createdAt
: A UNIX timestamp indicating the moment of creation.parent
: The id of the parent group, if applicable. optional
Errors
Key | Params | Property | Description |
---|---|---|---|
NOT_AUTHORIZED |
Returned if the user is not authorized for the operation. | ||
PROPERTY_REQUIRED |
Returned if a required parameter is missing. | ||
INVALID_ARGUMENTS |
Returned if a parameter does not fulfil requirements. | ||
THING_GROUP_NOT_FOUND |
id |
Returned if the thing group does not exist. |
DELETE
Required role: ReadWrite
Required privilege: ThingGroups.DELETE on thedomain
of the specified Thing Group
Required privilege: ThingGroups.READ on thedomain
of the specified Thing Group
Delete a thing group.
API Endpoint: [DELETE]
: /thing-groups/{id}
Request
Headers
Authorization
: The Authorization token returned from/auth/login
x-api-key
: The API Key to identify the request
Path
id
: The id of the thing group. required
Response
The response is an empty object ({}
).
Errors
Key | Params | Property | Description |
---|---|---|---|
NOT_AUTHORIZED |
Returned if the user is not authorized for the operation. | ||
PROPERTY_REQUIRED |
Returned if a required parameter is missing. | ||
INVALID_ARGUMENTS |
Returned if a parameter does not fulfil requirements. | ||
THING_GROUP_NOT_FOUND |
id |
Returned if the thing group does not exist. | |
THING_GROUP_HAS_THINGS |
id |
Returned if the thing group has things. | |
THING_GROUP_HAS_CHILD_GROUPS |
id |
Returned if the thing group has child groups. |
LIST
Required role: Read
Required privilege: ThingGroups.READ
Get all thing groups.
Note: This operation is eventually consistent. In other words, changes to the thing group might not be reflected immediately.
API Endpoint: [GET]
: /thing-groups?parent={parent}
Request
Headers
Authorization
: The Authorization token returned from/auth/login
x-api-key
: The API Key to identify the request
Query
parent
: The id of a thing group. If set, the results are filtered to only contain groups with this parent. optional
Response
groups[]
:id
: The id of the thing group.description
: The description.domain
: The domain.createdAt
: A UNIX timestamp indicating the moment of creation.parent
: The id of the parent group, if applicable. optional
Errors
Key | Params | Property | Description |
---|---|---|---|
NOT_AUTHORIZED |
Returned if the user is not authorized for the operation. | ||
PROPERTY_REQUIRED |
Returned if a required parameter is missing. | ||
INVALID_ARGUMENTS |
Returned if a parameter does not fulfil requirements. |
DESCRIBE
Required role: Read
Required privilege: ThingGroups.READ on thedomain
of the specified Thing Group
Get a thing group.
API Endpoint: [GET]
: /thing-groups/{id}
Request
Headers
Authorization
: The Authorization token returned from/auth/login
x-api-key
: The API Key to identify the request
Path
id
: The id of the thing group. required
Response
id
: The id of the thing group.description
: The description.domain
: The domain.createdAt
: A UNIX timestamp indicating the moment of creation.parent
: The id of the parent group, if applicable. optional
Errors
Key | Params | Property | Description |
---|---|---|---|
NOT_AUTHORIZED |
Returned if the user is not authorized for the operation. | ||
PROPERTY_REQUIRED |
Returned if a required parameter is missing. | ||
INVALID_ARGUMENTS |
Returned if a parameter does not fulfil requirements. | ||
THING_GROUP_NOT_FOUND |
id |
Returned if the thing group does not exist. |
ADD_THINGS
Required role: ReadWrite
Required privilege: ThingGroups.UPDATE on thedomain
of the specified Thing Group
Required privilege: ThingGroups.READ on thedomain
of the specified Thing Group
Required privilege: Things.UPDATE on thedomain
of each of the specified Things
Add thing(s) to a thing group.
API Endpoint: [POST]
: /thing-groups/{id}/things
Request
Headers
Authorization
: The Authorization token returned from/auth/login
x-api-key
: The API Key to identify the request
Path
id
: The id of the thing group. required
Body
thingNames[]
: A list of thingNames that will be added. required
Example body
{
"thingNames": ["my-thing-id", "another-thing-id"]
}
Response
The response is an empty object ({}
).
Errors
Key | Params | Property | Description |
---|---|---|---|
NOT_AUTHORIZED |
Returned if the user is not authorized for the operation. | ||
PROPERTY_REQUIRED |
Returned if a required parameter is missing. | ||
INVALID_ARGUMENTS |
Returned if a parameter does not fulfil requirements. | ||
THING_GROUP_NOT_FOUND |
id |
Returned if the thing group does not exist. | |
THING_GROUP_HAS_THING |
thingNames |
Returned if the thing group already contains a provided thing. | |
THING_NOT_FOUND |
thingNames |
Returned if a provided thing does not exist. |
REMOVE_THING
Required role: ReadWrite
Required privilege: ThingGroups.UPDATE on thedomain
of the specified Thing Group
Required privilege: ThingGroups.READ on thedomain
of the specified Thing Group
Required privilege: Things.UPDATE on thedomain
of the specified Thing
Remove a thing from a group.
API Endpoint: [DELETE]
: /thing-groups/{id}/things/{thingName}
Request
Headers
Authorization
: The Authorization token returned from/auth/login
x-api-key
: The API Key to identify the request
Path
id
: The id of the thing group. requiredthingName
: The name of the thing to remove. required
Response
The response is an empty object ({}
).
Errors
Key | Params | Property | Description |
---|---|---|---|
NOT_AUTHORIZED |
Returned if the user is not authorized for the operation. | ||
PROPERTY_REQUIRED |
Returned if a required parameter is missing. | ||
INVALID_ARGUMENTS |
Returned if a parameter does not fulfil requirements. | ||
THING_GROUP_NOT_FOUND |
id |
Returned if the thing group does not exist. | |
THING_NOT_FOUND |
thingName |
Returned if the provided thing does not exist. |
LIST_THINGS
Required role: Read
Required privilege: ThingGroups.READ on thedomain
of the specified Thing Group
The things in a thing group.
Note: This operation is eventually consistent. In other words, changes to the thing group might not be reflected immediately.
API Endpoint: [GET]
: /thing-groups/{id}/things
Request
Headers
Authorization
: The Authorization token returned from/auth/login
x-api-key
: The API Key to identify the request
Path
id
: The id of the thing group. required
Response
things[]
: A list of thing names
Errors
Key | Params | Property | Description |
---|---|---|---|
NOT_AUTHORIZED |
Returned if the user is not authorized for the operation. | ||
PROPERTY_REQUIRED |
Returned if a required parameter is missing. | ||
INVALID_ARGUMENTS |
Returned if a parameter does not fulfil requirements. | ||
THING_GROUP_NOT_FOUND |
id |
Returned if the thing group does not exist. |