Creating a Group

Any authenticated user can create a new group. The creator of a group becomes the group owner by default.

The following options can be combined for creating a group.

  • Whether the group ID is automatically assigned by Kii Cloud or specified on the client
  • Whether group members are specified or not when the group is created

This topic contains sample code for creating a group in the following three combinations of the options. Code parameters enable these combinations.

Creating a group with automatic ID assignment

Here is an example of creating a group.

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.GroupCreationRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups" \
  -d '{
        "name" : "testing group",
        "owner" : "{USER_ID}"
      }'

Specify the group name in the "name" field. The group name can be up to 190 characters. There is no restriction on the characters you can use. Multiple groups can have the same name.

Also, specify the user ID of the group owner in the "owner" field.

Kii Cloud will return the group ID with a 201 reponse as follows:

< 201
< Location: https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}
< Content-Type: application/vnd.kii.GroupCreationResponse+json
<{
  "groupID" : "{GROUP_ID}",
  "notFoundUsers" : []
}

If the specified group owner does not exist, the group creation will fail and a 404 response (USER_NOT_FOUND) will be returned.

You can use this group ID to retrieve the group later. Note that you cannot use the group name for referring the existing group.

Creating a group with members

When you create a group, you can also add its group members at the same time. Here is an example:

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.GroupCreationRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups" \
  -d '{
        "name" : "testing group",
        "owner" : "{USER_ID}",
        "members" : [
          "{USER_ID_OF_MEMBER_1}",
          "{USER_ID_OF_MEMBER_2}"
        ]
      }'

Specify the user ID of the group members in the "members" field.

When the group creation with the specified group members is successful, Kii Cloud will return a 201 response as in the previous example.

If any of the specified member(s) do not exist, the group will be created without them. In this case, Kii Cloud will send a list of non-existing users in the response as follows:

< 201
< Location: https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}
< Content-Type: application/vnd.kii.GroupCreationResponse+json
<
{
  "groupID" : "{GROUP_ID}",
  "notFoundUsers" : [ "{NON_EXISTING_USER_ID_1}", ... ]
}

You can also add group members later.

Creating a group with a specified ID

In the previous examples, the group ID is automatically assigned. You can also specify the group ID explicitly when you create the group.

The next sample is creating a new group, this time with its ID.

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.GroupCreationRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}" \
  -d '{
        "name" : "testing group",
        "owner" : "{USER_ID}"
      }'

Specify the group ID in {GROUP_ID}. The group ID can contain alphanumeric (lower-case only), period (.), dash (-), and underscore (_). The maximum length of the group ID is 30 characters. You will get an error if you try to set a group ID that duplicates with the existing one.

When the group creation is successful, Kii Cloud will return a 201 response as in the previous example.