Retrieving target details using the Common REST API

You can use the Common REST API (CRA) to retrieve target details for a specific product using the targets endpoint. This endpoint retrieves the target details and returns a JSON.

Before you begin

You must have the CRA installed and running. For more information, see Installing-and-configuring-the-Common-REST-API.
Log in to the service and acquire a token. For more information, see Logging-in-to-a-service-using-the-Common-REST-API.

Retrieving the list of systems using the systems endpoint

The targets endpoint uses the GET method to retrieve server details for a product. Use a URL based on the following structure:

https://<hostName>:<portNumber>/cra/serviceGateway/services/products/<productName>/targets

In SPE2410, we have deprecated the serviceName parameter from the URL. However, you can still use the existing URL.

https://<hostName>:<portNumber>/cra/serviceGateway/services/<serviceName>/products/<productName>/targets

The variables represent the following values:

<hostName> is the name of the mainframe host where the CRA server is running.
<portNumber> is the port number of the CRA server.
(Optional) <serviceName> is the service name you use to log in to a service. For more information, see To retrieve a list of services.

Important

By default, the service name is the one you have logged in to work with the API.

<productName> is the name of the product as it appears on the list. For more information, see Retrieving-a-list-of-installed-products-using-the-Common-REST-API.

Authorization

Name	Located in	Description
Authorization	header	Authorization token formatted as 'Bearer [token]'

Header parameters

This endpoint accepts the following query parameters:

Parameter	Description
serviceName	(Optional) Requested service
productName	(mandatory) Requested product
context	Context for the view Default: *
server	Usually is the PAS ID Default: *
sort	Sorting control string Generates an ORDER statement. You can sort up to 4 parameters Example: sort A.D&B.A A and B represent the IDs from a get view definition request.
filter	Generates a QWHERE clause Example: filter APPLID=CMF&SYSNAME=S*
Authorization	User token

Response body

On successful completion, the response body contains a JSON object containing the server data:

Property	Type	Description
productName	string	Product name
targets	array	Array of targets for each system monitored by the product
contexts	array	Array of all contexts that have active targets for the specific product

Each target object includes the following properties:

Property	Type	Description
targetName	string	Target name
description	string	Target description
status	string	Target status

Each context object includes the following properties:

Property	Type	Description
contextName	string	Context name Each context name can appear only once.
description	string	Context description
activeTargets	integer	Number of active targets discovered for the context in the selected product
filter	string	Generates a WHERE clause Only for contexts of type DEFINED.
type	string	Type of context Examples: SYSTEM, USER DEFINED, PREDEFINED

HTTP status and reason codes

The following HTTP status codes are returned for the indicated errors, and the response body is a standard error response body providing the reason code indicated and the associated error message.

Error Code	Explanation
200	Successful completion
403	Unauthorized. The authorization token is missing, invalid, or expired
404	The path is not valid. Most likely because the service in the URL does not exist.

Example

Request

The request example uses the following values:

<hostName> = myCRAhost
<portNumber> = 443
<serviceName> = Mva
<productName> = PLEXMGR

GET https://myCRAhost:443/cra/serviceGateway/services/Mva/products/PLEXMGR/targets
Authorization: Bearer {authToken}
Content-Type: application/x-www-form-urlencoded

Response

200 OK
Content-type: application/json
{
   "contexts": [
       {
           "filter": "",
           "contextName": "SJSF",
           "description": "Dynamic context SYSNAME:SJSF",
           "type": "SYSNAME",
           "activeTargets": 1
       },
       {
           "filter": [
               "%1=SJSD",
               "%1=SJSF"
            ],
           "contextName": "SJDF",
           "description": "SanJose D and F",
           "type": "DEFINED",
           "activeTargets": 2
       },
       {
           "filter": "",
           "contextName": "BMCPLEX1",
           "description": "Dynamic context SYSPLEX:BMCPLEX1",
           "type": "SYSPLEX",
           "activeTargets": 3
       },
       {
           "filter": [
               "TGTNAME = *"
            ],
           "contextName": "ALL",
           "description": "",
           "type": "DEFINED",
           "activeTargets": 3
       },
       {
           "filter": "",
           "contextName": "SJSC",
           "description": "Dynamic context SYSNAME:SJSC",
           "type": "SYSNAME",
           "activeTargets": 1
       },
       {
           "filter": "",
           "contextName": "SJSD",
           "description": "Dynamic context SYSNAME:SJSD",
           "type": "SYSNAME",
           "activeTargets": 1
       },
       {
           "filter": [
               "%2 = %6"
            ],
           "contextName": "CURRSYS",
           "description": "",
           "type": "DEFINED",
           "activeTargets": 1
       }
    ],
   "targets": [
       {
           "systemName": "SJSC",
           "targets": [
               {
                   "targetName": "SJSC",
                   "description": "Target Manager (6.3.00)",
                   "status": "Active"
               }
            ]
       },
       {
           "systemName": "SJSD",
           "targets": [
               {
                   "targetName": "SJSD",
                   "description": "Target Manager (6.3.00)",
                   "status": "Active"
               }
            ]
       },
       {
           "systemName": "SJSF",
           "targets": [
               {
                   "targetName": "SJSF",
                   "description": "Target Manager (6.3.00)",
                   "status": "Active"
               }
            ]
       }
    ],
   "productName": "PLEXMGR"
}