Web APIs

This topic presents an overview of Code PipelineAPIs and discusses authentication into BMC AMI Common Enterprise Services (CES) and authentication for notification WebHooks.

Documentation for APIs

API documentation for the Code Pipeline Web Interface is available here.

Overview diagram

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

Enabling Code Pipeline Web API

To use Code Pipeline's REST API, perform the following:

Make sure that the Code Pipeline CI Task has parameter WZCIXPRT defined. For more information, see the BMC AMI DevX Code Pipeline Installation and Configuration Guide.
Make sure that the Code Pipeline CM Task JCL includes ETPLIB, ETPLOG, WQPLIB, and WQPLOG DD statements. For more information, see the BMC AMI DevX Code Pipeline Installation and Configuration Guide.
Add WEBAPI=Y to the SDEFINI parameters file for the Code Pipeline CM Task. For more information, see the BMC AMI DevX Code Pipeline Installation and Configuration Guide.
Add the CES_HOSTNAME (or CES_HOST if PTF CXS028A is installed) and CES_PORT to the CMSC parameters. For more information, see the BMC AMI Enterprise Common Components Installation and Customization Guide.
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.
Ensure the following required software releases are installed and in use:

- Code Pipeline 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 Code Pipeline API requests with TSO credentials that have Code Pipeline 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.

Important

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. Code Pipeline 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' under Security Settings in the BMC AMI Common Enterprise Services online help.

Example

Header for Code Pipeline 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). Following is an example of the JSON Body.

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"
}],
}]
}