Topology services

The topology services is an application programming interface (API), which is implemented through industry standard Representational State Transfer (REST) services. A set of REST services is provided for working with the groups, sysplexes, central processor complexes (CPCs), and systems that are defined to z/OSMF, as described in this topic.

Table 1 lists the operations that the topology services provide.

Table 1. Operations provided through the topology services.
Operation	HTTP method and URI path
List the systems defined to z/OSMF	GET /zosmf/resttopology/systems
List the groups defined to z/OSMF	GET /zosmf/resttopology/groups
List the systems included in a group	GET /zosmf/resttopology/systems/groupName/<groupName>
List the sysplexes defined to z/OSMF	GET /zosmf/resttopology/sysplexes
List the systems included in a sysplex	GET /zosmf/resttopology/systems/sysplexName/<sysplexName>
List the systems included in a CPC	GET /zosmf/resttopology/systems/cpcName/<cpcName>

Required authorizations

To submit requests through the topology services, your user ID requires authorization to the Systems task provided in z/OSMF. Ensure that your user ID has READ access to the following resource profile in the ZMFAPLA class: <SAF-prefix>.ZOSMF.SETTINGS.SYSTEMS.VIEW. By default, users with user IDs connected to the IZUADMIN and IZUUSER security groups can access the topology services.

For information about client authentication in z/OSMF, see Authenticating to z/OSMF.

Content type used for HTTP response data

The JSON content type ("Content-Type: application/json") is used for response data. The following JSON object is used by all topology services for returning data about the requested operation:

{
 "items": "item-list",
 "numRows": "total-items"
}

where:

item-list: Array that contains the items that were retrieved. The attributes provided in the array depend on the requested operation.
total-items: Number of items retrieved.

Error handling

For errors that occur during the processing of a request, the API returns an appropriate HTTP status code to the calling client. An error is indicated by a 4nn code or a 5nn code. Some errors might also include a returned JSON object that contains a message that describes the error.

The following HTTP status codes are valid:

HTTP 200 OK: Success.
HTTP 400 Bad request: The request contained incorrect parameters.
HTTP 401 Unauthorized: The submitter of the request did not authenticate to z/OSMF or is not authorized to use the topology services.
HTTP 403 Forbidden: The server rejected the request.
HTTP 404 Bad URL: The target of the request (a URL) was not found.
HTTP 405 Method not allowed: The service does not support the HTTP method specified for the request.
HTTP 500 Internal server error: A programming error occurred.

Error logging

Errors from the topology services are logged in the z/OSMF log. You can use this information to diagnose the problem or provide it to IBM® Support, if required.

For information about working with z/OSMF log files, see IBM z/OS Management Facility Configuration Guide.