List the groups defined to z/OSMF

You can use this operation to obtain a list of the groups that are defined to a z/OSMF instance.

HTTP method and URI path

GET /zosmf/resttopology/groups

where:

zosmf/resttopology identifies the topology services.
groups informs the service that the request is to retrieve a list of the groups that are defined to the z/OSMF instance.

Standard headers

Use the following standard HTTP header with this request:

Content-Type: application/json

Custom headers

None.

Request content

None.

Usage considerations

See Usage considerations for the z/OSMF REST services.

Required authorizations

See Required authorizations.

Expected response

On completion, the service returns an HTTP response, which includes a status code indicating whether your request completed. Status code 200 indicates success. A status code of 4nn or 5nn indicates that an error has occurred. For more details, see Error handling.

If the request was successful, the response also includes the following JSON object:

{
 "items":[
   {
    "name":"group-name",
    "description":"group-description",
    "systemNickNames":"system-nicknames"
   }
 ],
 "numRows":"total-items"
}

where:

group-name: Name of the groups defined to z/OSMF. A value of <None> indicates that one or more systems are not assigned to a group.
group-description: Description of the group.
system-nicknames: Comma-separated list of the systems assigned to the group. Each system is identified by its nickname.
total-items: Number of groups that were retrieved.

Example

In the following example, the GET method is used to retrieve a list of the groups that are defined to the z/OSMF instance that has a host name of zosmf1.yourco.com.

Figure 1. Sample request to retrieve a list of groups

GET /zosmf/resttopology/groups HTTP/1.1
Host: zosmf1.yourco.com

A sample response is shown in Figure 2.

Figure 2. Sample response from a request to retrieve a list of groups

HTTP/1.1 200 OK
Date: Thu, 15 Jan 2015 05:39:28 +0000GMT
Connection: close

{
 "items":[
   {
    "name":"development",
    "description":"This group contains the systems used by development.",
    "systemNickNames":"sys1"
   },
   {
    "name":"production",
    "description":"This group contains the systems that are in production.",
    "systemNickNames":"sys2"
   },
   {
    "name":"test",
    "description":"This group contains the systems that are used for testing code.",
    "systemNickNames":"sys1,sys3"
   }
 ],
 "numRows":"3"
}