Using the Transformation Advisor APIs

Edit online

IBM Transformation Advisor provides a set of standard REST APIs. The APIs are compliant with OpenAPI specification 3.0.

BETA release

The APIs provided are not yet fully complete and are subject to change. Transformation Advisor is not yet compatible with earlier versions in relation to APIs. There is no guarantee that future releases will support these APIs. The good news is that we can and will make changes for you. Just ask!

API documentation

The Swagger documentation for the APIs is available from your Transformation Advisor installation at this location: <TA_SERVER>/openapi/. An interactive UI for these APIs can be found at: 
<TA_SERVER>/openapi/ui/

Finding the TA_SERVER value

The <TA_SERVER> value can be found from the OpenShift Cloud Platform using the following steps:

  1. Launch the OpenShift Cloud Platform Console UI.
  2. Click Home > Projects and select the project for Transformation Advisor.
  3. Click Networking > Routes and select the openapi-route.
  4. Find Location, which provides the value for <TA_SERVER>.

Limitations of Try it out

When running Transformation Advisor in OpenShift Cloud Platform with ingress enabled, the Try it out capability will fail on execution. This is because the generated curl command is missing the ingress value. You can add this value to the command and then run it manually to test the API.

Finding the TA_SERVER value with Transformation Advisor Local

The process for finding the <TA_SERVER> value is different if you are using Transformation Advisor Local (available from the IBM Garage Methodology website ).

  1. From the location where you run Transformation Advisor Local, issue this command: docker ps.
  2. Look for the image with server in the name and check the value of the port.
    • The default value is 2220, as in this example: 9443/tcp, 0.0.0.0:2220->9080/tcp.
  3. Go to this URL: <TA_LOCAL_UI_URL>:<SERVER_PORT>/openapi/ui/.

Server authentication

If authentication is enabled for Transformation Advisor, it is necessary to pass credentials with each API call. The Swagger API provides the means to pass the necessary credentials.

- In some cases, the API will return a URL as a result.
- Usually it is not possible to use the URL directly as you will also have to provide credentials.
- In these cases you need to use the appropriate tools to add the credentials as headers.
- The exact format for the headers can be seen in the curl command the Swagger API produces.

The required values to pass credentials are detailed in the following information:

API user token

To access the APIs using your own user token, complete the following steps:

  1. Launch the OpenShift Cloud Platform Console UI.
  2. Click on the user dropdown and select Copy Login Command.
  3. Click Display Token.
  4. Copy the value of the token attribute.
  5. Enter this value into the apiKey field in the OpenAPI UI.

API key creation

To access the APIs without relying on a user token, complete the following steps to create a service account and use the API associated with that account.

  1. Launch the OpenShift Cloud Platform Console UI.
  2. Click on the user dropdown and select Copy Login Command.
  3. Click Display Token.
  4. Execute the Login command.
  5. Create the service account, in this case called ta-api. 
    oc create sa ta-api
  6. Describe the service account. 
    oc describe sa ta-api
  7. This will list a set of Mountable secrets. Describe the first token secret. 
    oc describe secret ta-api-secret-<TOKEN>
  8. Copy the value of the token attribute.
  9. Enter this value into the apiKey field in the OpenAPI UI.

API REST client

To easily integrate Transformation Advisor APIs into your product or tool, an open source REST client is being developed and will be available at a later date.