Help

Web APIs

This topic presents an overview of ISPW APIs and discusses authentication into Compuware Enterprise Services (CES) and authentication for notification WebHooks.

Documentation for APIs

API documentation for the ISPW Web Interface is available here.

Overview Diagram

This illustration depicts the interrelationships between the various components involved in an ISPW REST API implementation.

Enabling ISPW Web API

To use ISPW's REST API, perform the following:

  1. Ensure the ISPW CI Task has parameter WZCIXPRT defined. For more information, see Table 4-1 in the ISPW Installation and Configuration Guide.

  2. Ensure the ISPW CM Task JCL includes ETPLIB, ETPLOG, WQPLIB, and WQPLOG DD statements. For more information, see Figure 4-4 in the ISPW Installation and Configuration Guide.

  3. Add WEBAPI=Y to the SDEFINI parameters file for the ISPW CM Task. For more information, see Table 4-3 in the ISPW Installation and Configuration Guide.

  4. Add the CES_HOSTNAME (or CES_HOST if PTF CXS028A is installed) and CES_PORT to the CMSC parameters. For more information, see the Enterprise Common Components Installation and Customization Guide.

  5. Within CES Administration > Security, Add/Create a new Personal Access Token. For more information on adding or creating a Token, see the CES online Help topic "Personal Access Tokens Settings".

  6. Ensure the following required software releases are installed and in use:

    • ISPW 18.02 with current maintenance

    • ECC 17.02 with current maintenance

    • CES 18.02.02 (at a minimum)

Authentication via CES

Authentication is accomplished using a personal access token to associate ISPW API requests with TSO credentials that have ISPW authorization. To create a personal access token, select the CES menu button in the upper left corner and, under Administration, select Security. In the Security area, select Personal Access Tokens. The Personal Access Tokens page appears, from which you can create and manage personal access tokens.

Note: Because security and personal access tokens are administrative features, the Personal Access Tokens page may not be accessible for users without administrative privileges. An administrator will need to create tokens for users without administrative access.

The personal access token is stored in CES and is used to make requests to the host on behalf of the authorized user. HTTPS is recommended to ensure this token and all requests are encrypted. ISPW API calls must include the header "Content-Type" with a value of "application/json", and the header "Authorization" with the value of your personal access token. (For more information, see "Personal Access Tokens Settings" in the Compuware Enterprise Services help topic Security Settings.)

Example: Header for ISPW API Calls

Authorization: c343114a-a991-40b9-afe6-4846064175e2
Content-Type: application/json

Authentication for Notification WebHooks

If authentication is required for third party notifications, resource calls must be made using the httpHeaders or credentials JSON objects. This authentication is available at the global level (one set of credentials for all callbacks) and at the callback level (credential override for a specific callback). An example of JSON Body is provided below.

Example: Global Basic Authentication with One Overridden Callback Using httpHeaders

{
    "credentials":{                                           //Use basic authentication for all calls
        "username": "JohnDoe",
        "password": "xxxxxxx"
    },
"events": [{
   "name":"completed",
    "url":"http://myserver:48080/ISPW/Complete"
    },
    {
    "name":"failed",
    "url":"http://otherserver:48080/ISPW/Fail",
    "httpHeaders": [{                                     //Overide global credentials with httpHeaders
        "name":"Authorization",
        "value":"123-456-789"
        }],
    }]
}