Example: Group Management REST API

This example shows how to use the cloud operations Group Management REST API for typical group management actions.

The example takes you through displaying groups and members of groups, adding members to and deleting members from system groups. For a list of the system groups for each of the capabilities, see System groups.

Before you begin

All API calls require a valid cross site forgery request (CSRF) token in the IBM-CSRF-TOKEN header of the call. Obtain a CSRF token by using POST /instance/services/csrf_token. For more information, see Preventing cross site request forgery.

Display groups and their members

Use the following call to display the groups:

GET /instance/services/groups

To filter the list of groups to include a particular string, include a search term in the call, for example, Administrators:

GET /instance/services/groups?search_term=Administrators

If no groups match the search term, the JSON object returned by the call contains an empty list.

To include the group members in the groups list, add the optional_parts parameter to the call. Be aware that this parameter can significantly affect the performance of the call and you should use it in combination with search terms or paging.

GET /instance/services/groups?search_term=Administrators&optional_parts=members

Add members to a system group

Your cloud subscription includes the following system user groups: Administrators, Operators, Participants, Developers, and Testers. For example, to add new members to the Administrators group use the following call and include the user IDs of the new members in the body of the call:

POST /instance/services/groups/Administrators/members
...
{
 "group_members": [
    {
      "member_id": "john.smith@host.com",
      "type": "user"
    },
    {
      "member_id": "jane.brown@host.com",
      "type": "user"
    }
  ]
}

Update member information for a system group

You can update the member information by sending the complete JSON object, including all members of the group, in the body of the call. For example, if John Smith and Jane Brown move to the test team and their administrative responsibilities are completely taken over by David Short and Ann Jones, replace John and Jane's names in the JSON object that you send with the call with David and Ann's names:

PUT /instance/services/groups/Administrators/members
...
{
 "group_members": [
    {
      "member_id": "david.short@host.com",
      "type": "user"
    },
    {
      "member_id": "ann.jones@host.com",
      "type": "user"
    }
  ]
}

The stored user information is completely replaced with the information that is sent in the request body. If you omit properties from the JSON object, for example, if you omit users from the group members list, the users are removed from group.

Tip: Take care when updating member information. If you forget to include the JSON object with the call, you will remove all the members from the group you are updating.

Delete members from a system group

For example, to delete members from the Administrators group, use the following call:

DELETE /instance/services/groups/Administrators/members
...
{
 "group_members": [
    {
      "member_id": "john.smith@host.com",
      "type": "user"
    },
    {
      "member_id": "jane.brown@host.com",
      "type": "user"
    }
  ]
}