Group

Location /api/apps/{appID}/groups/{groupID}
This resource represents a group belonging to an application in Kii Cloud.

Request Headers (Applies to all methods)

Authorization
header
Required: Yes

PUT

/api/apps/{appID}/groups/{groupID}

Description

Create a new group with a given groupID.

The maximum size of the groupID is 30 characters and must follow the pattern [a-z0-9_\-\.]*. The owner will be added as a group member by default.

Security

An anonymous and thing access is not allowed for this method. If accessing as the administrator, an owner is not required.

Content-Type application/vnd.kii.GroupCreationRequest+json

All the required data for creating the group.

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
URL Params
Name Required? type Description
groupID Yes string ID of the group.
Params
Name Required? Type Description
name Yes string The name of the group.
owner string The userID of the group owner.
members string A collection of the group member's userIDs.
Sample Request 
{
  "name": "[string]",
  "owner": "[string]",
  "members": "[string]"
}
Responses
201

Content-Type application/vnd.kii.GroupCreationResponse+json

The group has been created successfully.
Headers
Name Type Description
Location string URI of the created group.
Contents
Name Type Description
groupID string The ID of the created group.
notFoundUsers string The collection of userIDs of the users who were not found and thus not added as the group members.
400

Content-Type application/vnd.kii.ValidationException+json

The given groupID was invalid.
Contents
Name Type Description
errorCode string Error code "INVALID_INPUT_DATA".
message string The error message.
409

Content-Type application/vnd.kii.GroupAlreadyExistsException+json

A group with the same groupID already exists.
Contents
Name Type Description
errorCode string Error code "GROUP_ALREADY_EXISTS".
message string The error message.
groupID string The ID of the group.
appID string The ID of the application.
404

Content-Type application/vnd.kii.UserNotFoundException+json

The user was not found.
Contents
Name Type Description
errorCode string Error code "USER_NOT_FOUND".
message string The error message.
field string The field used for searching the user. This can be the userID or address field.
value string The field value used for searching the user.
appID string The ID of the application.
401

Content-Type application/vnd.kii.UnauthorizedAccessException+json

Not authorized to create the group.
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).

GET

/api/apps/{appID}/groups/{groupID}

Description

Get the data of the group.

Security

An anonymous access is not allowed for this method.

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
URL Params
Name Required? type Description
groupID Yes string ID of the group.
Responses
200

Content-Type application/vnd.kii.GroupRetrievalResponse+json

The data of the group has been retrieved successfully.
Contents
Name Type Description
groupID string The ID of the group.
name string The name of the group.
owner string The userID of the group owner.
404

Content-Type application/vnd.kii.GroupNotFoundException+json

The group was not found.
Contents
Name Type Description
errorCode string Error code "GROUP_NOT_FOUND".
message string The error message.
groupID string The groupID of the group.
appID string The ID of the application.
401

Content-Type application/vnd.kii.UnauthorizedAccessException+json

Not authorized to retrieve the group.
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).

DELETE

/api/apps/{appID}/groups/{groupID}

Description

Delete the group.

Security

Only the administrator and the group owner can perform this operation.

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
URL Params
Name Required? type Description
groupID Yes string ID of the group.
Responses
204

Content-Type (None)

The group has been deleted successfully.
Note This response has no contents.
404

Content-Type application/vnd.kii.GroupNotFoundException+json

The group as not found.
Contents
Name Type Description
errorCode string Error code "GROUP_NOT_FOUND".
message string The error message.
groupID string The groupID of the group.
appID string The ID of the application.
401

Content-Type application/vnd.kii.UnauthorizedAccessException+json

Not authorized to delete the group.
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).