Relationship between a User and a Group

A user can be associated with a group by two types of relationships: user relationship and owner relationship. A user and a group are related to each other with two-way links.

When a group member is added or removed or a user or a group is deleted, Kii Cloud automatically updates those two-way links.

  • Member

    A member is a user who joins a group. A group member can access the group data (i.e., KiiObjects in the group-scope bucket) by default.

  • Owner

    An owner is a user who owns a group. The user who creates a group will become the initial owner. The owner can add and remove group members (For more information, see Group Access Control).

    A group owner is also a member of the group.

    You can change the group owner through the REST API. When the new owner is specified, they automatically become a group member.

Relationship between a User and a Group

An owner and a member are expressed as two-way relationships between a user and a group.

Kii Cloud has user and group APIs that return a relationship between a user and a group. The user APIs point to group objects and vice versa as shown in the figure below.

The figure also shows the multiplicity of instances in each API in the UML notation (A user and a group are described as KiiUser and KiiGroup as referred to in the Kii Cloud SDK). That is, "0..*" means 0 or more and "0..1" means 0 or 1. Each instance can be related to 0 or more instances except that a group can be related only to 0 or 1 owner.

The figures in this topic use parts and parameters of the REST API URLs to express equivalents of the Kii Cloud SDK methods. For more information, see sample code in the subtopics of this topic.

  • Getting a Group List for a Member

    Specify the is_members={USER_ID} parameter in a GET request to the group collection URL /api/apps/{APP_ID}/groups. Kii Cloud returns a list of KiiGroups that the KiiUser with the specified ID is a member of. If the KiiUser does not belong to any group, an empty list is returned.

  • Getting a Group List for an Owner

    Specify the owner={USER_ID} parameter in a GET request to the group collection URL /api/apps/{APP_ID}/groups. Kii Cloud returns a list of KiiGroups that the KiiUser with the specified ID is the owner of. The returned KiiGroups are always included in the response to a GET request with the is_members={USER_ID} parameter because the owner is also a member of their group. If the KiiUser does not own any group, an empty list is returned.

  • Getting a Member List of a Group

    The groups/{GROUP_ID}/members endpoint returns a list of KiiUsers that are members of the KiiGroup with the specified ID. This works in the opposite way of the is_members={USER_ID} parameter.

  • Getting the Owner of a Group

    The owner field in the response to a GET request to the groups/{GROUP_ID} endpoint holds a user that is the owner of the KiiGroup with the specified ID. One KiiUser is returned because a group cannot have multiple owners. This works in the opposite way of the owner={USER_ID} parameter.

When a group owner who is the sole member of their group is deleted, the group has no member. In this case, the groups/{GROUP_ID}/members endpoint nor the owner field of the groups/{GROUP_ID} endpoint does not return any valid user. For more information, see Considerations in deleting users.

Example of manipulating user-group relationships

See the figure below for the results of the following three actions.

  1. Alice creates the Sales Div. group. Relationships created from this action are indicated by the red arrows.

  2. Alice adds Bob to the Sales Div. group. Relationships created from this action are indicated by the blue arrows.

  3. Bob creates the Tennis Club group. Relationships created from this action are indicated by the green arrows.

The figure indicates that all the relationships between the users and the groups are symmetrical.

However, the REST API calls for listing users and groups return a different number of objects. For example, a call to Bob's endpoint with the is_members={USER_ID} parameter returns Sales Div. and Tennis Club while a call to Tennis Club's endpoint groups/{GROUP_ID}/members returns only Bob. Also, Sales Div.'s endpoint groups/{GROUP_ID}/members returns Bob and Alice.

When you implement your mobile app, be careful about the type of objects, KiiUsers or KiiGroups, in your listing operation.

Retrieving a group for its member or owner

You can retrieve group data by using a GET request to the group collection endpoint with the user ID in addition to the methods of using the group URI or ID.

You can get groups that are related to the logged-in user or a specific user by getting a list of KiiGroups with the is_members={USER_ID} parameter. Then, you can perform desired actions through accessing KiiObjects in the group scope and getting a list of group members.

You need to implement logic to distinguish retrieved groups in your mobile app. The group listing feature just gets KiiGroups that are related to the target KiiUser and it is not possible to know the role of each KiiGroup in the list. Suppose your mobile app has a bulletin board feature and a group chat feature. You could not distinguish KiiGroups in the group list for the bulletin board and the group chat. In order to use those groups separately by purpose, you would need to develop your mobile app accordingly.