Group APIs examples

This section lists the group APIs examples that you can refer to.

It is assumed that you already get the following values. For more information, see Prerequisites. 

export ACCESS_TOKEN="Bearer <access_token>"
export ACCOUNT_ID="<account>"
export BASE_URL="<route-to-service>"

Create a group

Run the following command to create a group. 

curl -X POST "${BASE_URL}/applicationmgmt/v1/groups" \
  -H "Authorization: ${ACCESS_TOKEN}" \
  -H "X-TenantID: $ACCOUNT_ID" \
  --data '{"name":"CriticalServices","type":"standard","description":"Services that must stay up!","policyVersion":"static"}'

Fetch a group and grant access

The following example assumes that you create group that is named CriticalServices.

Note: Ensure that the team is in the same account as the group. To create a team for an account, make sure you are logged in as the AccountAdministrator for the account.

  1. Run the following command to get the account ID:

    cloudctl iam accounts

    You can get the following output:

    ID         Name
5a56-3f9b  my-account

  2. Run the following command to get the team ID:

    cloudctl iam teams

    You can get the following output:

    ID       Name     Groups   Users   Account
my-team  my-team  0        1       my-account

  3. Run the following command to grant access:

    cloudctl iam resource-add my-team -r "crn:v1:icp:private:ibmcloudappmgmt-cp4mcm-perfmon-applicationmgmt:mycluster:a/5a56-3f9b::resource-group:CriticalServices"

Query for groups

The backend supports filtering by policyVersion. Groups can also be queried without a filter that allows the retrieval of all individual groups the user has access to.

Run the following Command to run a query:

curl -X GET "${BASE_URL}/applicationmgmt/v1/groups?filter=policyVersion=static&field=name" \
  -H "Authorization: ${ACCESS_TOKEN}" \
  -H "X-TenantID: $ACCOUNT_ID"

You can get the following output (shortened for brevity):

{
  "items":[
    {
      "name":"CriticalServices",
    },
    {
      "name":"some-group",

    },
    {
      "name":"some-group-1",

    }
  ],
  "nextOffset":"some-string"
}

Pagination

Groups are fetched one page at a time. Use the nextOffset property in the result to fetch more pages. The nextOffset property is an empty string when no extra pages remain. Do NOT rely on a set number of results being returned in one page. To retrieve the next page, use nextOffset from the previous result.

Run the following command to get more pages: 

curl -X GET "${BASE_URL}/applicationmgmt/v1/groups?filter=policyVersion=static&field=name&offset=some-string" \
  -H "Authorization: ${ACCESS_TOKEN}" \
  -H "X-TenantID: $ACCOUNT_ID"

You can get the following output:

{
  "items":[
    {
      "name":"some-group-57",
    },
    {
      "name":"some-group-58",
    }
  ],
  "nextOffset":""
}

Because nextOffset is an empty string, no additional results remain.

Update a group

This example assumes that you want to update the group that you create with the name CriticalServices.

Run the following command to update: 

curl -X POST "${BASE_URL}/applicationmgmt/v1/groups/CriticalServices" \
  -H "Authorization: ${ACCESS_TOKEN}" \
  -H "X-TenantID: $ACCOUNT_ID" \
  --data '{"description":"Services that are essential to customers"}'

Note: You can use this command to add members to a group(see the following command). The following example assumes that your environment has the uids exampleuid_kafkatest-zookeeper and exampleuid2_k8sStatefulSet-zookeeper.

curl -X POST "${BASE_URL}/applicationmgmt/v1/groups/CriticalServices" \
  -H "Authorization: ${ACCESS_TOKEN}" \
  -H "X-TenantID: $ACCOUNT_ID" \
  --data '{"policyVersion":"static","policy":[[{"field":"uid","equal":"exampleuid_kafkatest-zookeeper"}],[{"field":"uid","equal":"exampleuid2_k8sStatefulSet-zookeeper"}]]}'

Fetch the members of a group

This example assumes that you create a group that is named CriticalServices.

Run the following command to fetch members of a group:

curl -X GET "${BASE_URL}/applicationmgmt/v1/groups/CriticalServices/members?field=uid" \
  -H "Authorization: ${ACCESS_TOKEN}" \
  -H "X-TenantID: $ACCOUNT_ID"

You can get the following output:

{
  "items":[
    {
      "uid":"exampleuid_kafkatest-zookeeper"
    },
    {
      "uid":"exampleuid2_k8sStatefulSet-zookeeper"
    }
  ],
  "nextOffset":""
}

Note: If group members exceed a single page, pagination through group members is performed in the same matter as it is for groups (For more information, see Pagination. Provide the returned nextOffset as the offset for the next request.

Fetch the number of members in a group

This example assumes that you create a group that is named CriticalServices.

Run the following command to fetch the number of members in a group: 

curl -X GET "${BASE_URL}/applicationmgmt/v1/groups/CriticalServices/member_counts" \
  -H "Authorization: ${ACCESS_TOKEN}" \
  -H "X-TenantID: $ACCOUNT_ID"

You can get the following output:

{
  "name":"CriticalServices",
  "count":2,
  "retrievedAt":"2020-04-16T07:23:16Z"
}

Note: For performance reasons, the returned count might be a cached result. Do not depend on this value being accurate.

Retrieve the number of members in multiple groups

This example assumes that you create three groups that are named CriticalServices, group2, and group3.

Run the following command to get the number of members in multiple groups: 

curl -X POST "${BASE_URL}/applicationmgmt/v1/groups/member_counts/query" \
  -H "Authorization: ${ACCESS_TOKEN}" \
  -H "X-TenantID: $ACCOUNT_ID" \
  --data '["CriticalServices", "group2", "group3"]'

You can get the following output:

{
  "counts": {
    "CriticalServices": 2,
    "group2": 0,
    "group3": 1
  },
  "retrievedAt": {
    "CriticalServices": "2020-04-16T07:23:16Z",
    "group2": "2020-04-16T07:23:16Z",
    "group3": "2020-04-16T07:23:16Z"
  }
}

Note: For performance reasons, the count that is returned might be a cached result. Do not depend on this value being accurate. If groups exceed a single page, pagination is performed in the same matter as it is for groups (For more information, see Pagination). Provide the returned nextOffset as the offset for the next request.

Delete a group

This example assumes that you create a group that is named CriticalServices and you want to delete it.

Run the following command to delete a group: 

curl -X DELETE "${BASE_URL}/applicationmgmt/v1/groups/CriticalServices" \
  -H "Authorization: ${ACCESS_TOKEN}" \
  -H "X-TenantID: $ACCOUNT_ID"

Note: Deletion is an asynchronous operation.