APIs

Swagger documentation

When the Unified Management Server is running, you can open API Swagger documentation by opening the following URL in a browser:

https://<host>:<port>/ws/swagger-ui.html

where <host>:<port> are the host name or IP address, and the port number, of the Unified Management Server host computer. The port number is specified by the components.izp.server.port parameter, and its default value is 12023.

By default, the documentation displays the latest version. To find an older version, select it from the drop-down list. Only the endpoints of data management experiences that have been purchased and activated are available. Deprecated endpoints are gray, and the text is struck through.

Specifying versions in REST calls

To specify the version of an end point to use in a REST API call, you can use the X-API-VERSION header with any of the following values:

No value (or not using the header): Calls the newest available version of the endpoint.
LATEST: Calls the newest available version of the endpoint.
EARLIEST: Calls the earliest available version of the endpoint.
<version>: Calls the specified version, for example "1.1.0.0". You can specify any version that is available in the Swagger documentation.

Tip: It is recommended to use X-API-Version for pipelines or programs that leverage UMS APIs.

If you have coded the pipeline or programmed the plug-in for Unified Management Server 1.1 (UI78605), pass the X-API-VERSION header. For example, pass X-API-Version: 1.1.0.8 for Unified Management Server 1.1 (UI78605). This ensures your pipeline or program will work even if features are changed or scheduled to be removed. You can upgrade the X-API-VERSION header after testing future PTFs in your environment.

For information on deprecated and removed functions in Unified Management Server 1.2, see Deprecated and removed functions in Unified Management Server.

New endpoints support

All REST API endpoints will authenticate incoming requests using the data in HTTP Auth Header. The Auth Header value must be "Bearer <access token>". The following three endpoints are supported in IBM® Unified Management Server for z/OS® 1.1.0.3.

Session start: Invoke the login endpoint to initiate your session.

POST ws/security/login

body {"id" : "username", "password" : "password"}

response

{
    "id": "username",
    "accessToken": "access-token",
    "refreshToken": "refresh-token",
    "accessTokenExp": 1614102132084,
    "refreshTokenExp": 1614186732084
}

Session operations: Invoke other REST endpoints that form the main part of the session. During the session, invoke the refresh-token endpoint whenever you need to refresh the accessToken.

POST ws/security/refresh-token

body

{
    "id":"username",
    "refreshToken":"refresh-token"
}

response 

{
    "id": "username",
    "accessToken": "access-token",
    "refreshToken": "refresh-token",
    "accessTokenExp": 1614102132084,
    "refreshTokenExp": 1614186732084
}

Session end: End the session by invoking the logout endpoint.

POST ws/security/logout

body

{
    "id":"username"
}

response: 

http status 200

Login endpoint issues access and refresh tokens. The following default validity is applied:

Default access token: 30 minutes
Refresh access token: 24 hours

Expiration time is epoch time in milliseconds. Refresh endpoint is used to refresh the access token. When the access token expires, users can use the refresh token to get a new access token. Logout operation is used to clear tokens in Unified Management Server.

When the UMS authentication type (authType) is configured as MFA_JWT, the refresh endpoint is not supported, and a negative value is returned as the refresh token expiration time in response to the login request. With this authType, you need to evaluate the access token expiration time before issuing any service request with the token, and if it is about to expire soon, call the login endpoint again with your user credential provided to get a new access token.

URL encoding

Modern APIs accept both <uuid> and <name> as parameters. If you are using <name> as a parameter or in the URL, we recommend encoding the URL to handle special characters, such as #, ?, %, /, and others. Refer to the following code samples:

Jenkins

siteRuleNameConverted = URLEncoder.encode(siteRuleName, "UTF-8")

Python

from urllib.parse import urlparse
siteRuleNameConverted = urllib.parse.quote_plus(siteRuleName)

Specifying error response levels

When you start the Unified Management Server, you can add apiErrorResponseLevel flag to set the level of detail in error messages returned by the API. For example:

-apiErrorResponseLevel <0|1|2>

where the value of "0" is minimal details, the value of "1" is partial details, and the value of "2" is full details. If a detailed level is not specified when you start the server, the default level is 0.

Support for APIs

/policy/pull-requests/{pullRequestId}/approve: Approve a pull request. The changes have been reviewed, and the work can be merged with the originating application or associated applications.; Note: If you want to remove the dropped objects from an application, use the requestBody parameter to approve the pull request. This parameter is available in Db2® DevOps Experience 1.3.0.10 release.
/policy/pull-requests/{pullRequestId}/needs-work: Need more information. The pull request cannot be merged to the originating application or associated applications in its current state.; Note: If you do not want to remove the dropped objects from an application, use the requestBody parameter to disapprove the pull request. This parameter is available in Db2 DevOps Experience 1.3.0.10 release.

The following pull request APIs are available in Db2 DevOps Experience 1.2.0.5 release:

/policy/pull-requests/report: Get pull request reports based on Category, Status, and Date Time Range.
/policy/pull-requests/report/application/{applictionId}: Get pull request reports for an application based on the Category, Status, and Date range.
/policy/pull-requests/report/instance/{instanceId}: Get pull request reports for an instance based on the Category, Status, and Date range.
/policy/pull-requests/report/team/{teamId}: Get pull request reports for a team based on the Category, Status, and Date range.

The following APIs are available in the Db2 DevOps Experience 1.3.0.10 release.

/policy/pull-requests/{pullRequestId}/convertWslToIspf=true

Edit and import the Work Statement List to resume the flow of the API parameter that was added to the 'Merge/Approve/Resume/Revert' POST API.

Note: The convertWslToIspf API parameter is available only with the Resume-Merge API option.

/policy/instances/{instanceId}/objects/drop

Mark the objects that need to be dropped from an instance.

Note: This API currently supports marking the index (object type) in an instance for dropping.

To mark the objects to be dropped, provide the values in the objectName and Type parameters, and set the markAsDrop parameter to true in the API.
Note: If you want to unmark the objects from the drop list, set the markAsDrop parameter to false.
To remove the object from an instance, go to the Instance Details Edit DDL page of the instance in the user interface (UI) and click Apply all changes. You can review the list of dropped objects in the Confirm DDL changes dialog box and then click Apply all changes.

Note: The dropped object must either be approved or disapproved, using the requestBody parameter in the approve or need work APIs, respectively. For more information, refer to Reviewing and approving pull requests.