Getting Started With the IBM App Connect Public API

If you are looking to create App Connect resources programmatically or provide your own monitoring and administration capabilities, this article offers an introduction to using the public API, with a worked example using Bash for those looking to get started.

With the App Connect public API, you can programmatically perform the following tasks:

• Create and administer integration runtimes.
• Create and administer configurations.
• Create and administer BAR Files.
• Create and administer traces for an integration runtime.

In Part One, we are going to:

1. Create a configuration that gives us access to a GitHub repository that stores a BAR file. If you use a public repository, the configuration won’t actually be used, since my repository is public. If you were to use a private repository, the configuration would be necessary so App Connect can authenticate and pull in the BAR file from your repository.
2. Create an integration runtime that will use the configuration.
3. Call the flow’s endpoint that's running on our integration runtime.

In Part Two, we will then do something more advanced that involves:

1. Creating a new BAR file that contains a different flow from what is in the GitHub repository.
2. Creating a new integration runtime that will run this BAR file.
3. Editing the first integration runtime to use the BAR file that we have created and observing the changes.

We will finish by cleaning up all of the above resources.

At the time of this post, you can use this feature in:

• North Virginia
• Frankfurt
• London
• Sydney
• Jakarta
• Mumbai

Prerequisites

• You need a current App Connect trial or paid subscription. For more information, see App Connect on AWS.
• From the App Connect Dashboard for your instance, navigate to the Settings panel and click the "Public API credentials" tab.
• Click on the "Generate" button and enter a name when prompted. This will give you a client ID and a client secret. Keep these safe and consider them both sensitive.
• From the same page, you will see a link to generate an API key. You will need to follow the steps on that page as well to get an API key.
• Once you have the client ID, client secret, and API key, these are not expected to change frequently. The current expiry date at the time of this post is two years.
• You will use these three pieces of information as well as your App Connect instance ID to generate an access token that you can use to interact with App Connect.

You will need to use this access token for your operations. Note that at the time of this post, this access token will be active for a period of 12 hours only. To get the access token, you will need to use your client ID, client secret, API key, and instance ID, with our /api/v1/tokens POST endpoint.

Your token will not automatically renew, so make sure you call this often enough to be able to continue with your App Connect API requirements.

Here is the API overview.

Note that the format of the token is a JSON Web Token and within the token, you will be able to determine its expiry date. Continue only once you have your token.

What follows is a worked example that combines the above information with code snippets for you to adjust for your own needs. Note that for this example I have chosen to use Bash.

As our API accepts JSON payloads, you will find lots of quotes around the strings: it is expected that you might use a request helper application or perform your API calls using a language that lets you easily create HTTP requests such as JavaScript, TypeScript, Node.js, Go, or Java – the choice is yours.

To view the API documentation, click "API specification" on the Public API credentials page. You can also see the complete API specification in our documentation.

Getting Started

Make sure you have the following values to hand (in my example, I am going to set them as variables in my Bash shell, because they are going to be used a lot):

1. Your App Connect instance ID, which I will be setting and using in the cURL commands with:
   export appConInstanceID=<the instance ID>
2. Your App Connect client ID, which I will be setting and using in the cURL commands with
   export appConClientID=<the client ID>
3. Your App Connect authentication token (that you made earlier and lasts twelve hours), which I will be setting and using in the cURL commands with:
   export appConToken=<the App Connect authentication token>
4. The App Connect endpoint that your instance is valid for, which I will be setting and using in the cURL commands with:
   export appConEndpoint=<the endpoint>

The endpoint can be set to any of the regions that we mention above (check the documentation for the latest availability) but be aware of your own data processing and any regional needs - you may want to use the endpoint closest to you, or you may have legal, or data handling, requirements to use only a particular region.

You can determine this endpoint from the OpenAPI document that can be downloaded from within App Connect, or via the public documentation we provide.

Part One

Creating a Configuration

Note that configuration documentation applicable for this environment is available on the configuration types for integration runtimes page.

In this example, you will create a configuration that stores a personal access token for a GitHub repository that contains a BAR file.

Make sure that you have your personal access token to hand, with sufficient access scope and restrictions as you see fit. It is important that you keep this token to yourself.

This personal access token is not to be confused with the token you will be using with App Connect. It is an example of a sensitive piece of data (in the form of an App Connect configuration) and is used for simplicity’s sake.

myGitHubToken="thetokenhere" 
gitHubAuthData=" 
  { 
  \"authType\":\"BASIC_AUTH\", 
  \"credentials\":{ 
    \"username\":\"token\", 
    \"password\":\"${myGitHubToken}\" 
  } 
} 
encodedAuthData=$(echo -e "${gitHubAuthData}" | base64) 

configurationBody="{ 
    \"metadata\": { 
        \"name\": \"my-github-configuration\" 
    }, 
    \"spec\": { 
        \"data\": \"${encodedAuthData}\", 
        \"description\": \"Authentication for GitHub\", 
        \"type\": \"barauth\" 
   } 
}" 

curl -X POST https://${appConEndpoint}/api/v1/configurations \ 
    -H "x-ibm-instance-id: ${appConInstanceID}" \ 
    -H "Content-Type: application/json" \ 
    -H "Accept: application/json" \ 
    -H "X-IBM-Client-Id: ${appConClientID}" \ 
    -H "authorization: Bearer ${appConToken}" \ 
    -d "${configurationBody}" 

If successful, you will then be able to see the configuration in the App Connect Dashboard.

You could also perform an HTTP GET call to either list all configurations you have access to, or to get a particular configuration’s details.

To get all instances of a particular resource (in this case, a configuration), you would use the following command:

curl -X GET https://${appConEndpoint}/api/v1/configurations \ 
    -H "x-ibm-instance-id: ${appConInstanceID}" \ 
    -H "Content-Type: application/json" \ 
    -H "Accept: application/json" \ 
    -H "X-IBM-Client-Id: ${appConClientID}" \ 
    -H "authorization: Bearer ${appConToken}" 

To perform an HTTP GET operation on a named resource (in this case, called "my-github-configuration" that we created earlier), you would use the following command:

curl -X GET https://${appConEndpoint}/api/v1/configurations/my-github-configuration \ 
    -H "x-ibm-instance-id: ${appConInstanceID}" \ 
    -H "Content-Type: application/json" \ 
    -H "Accept: application/json" \ 
    -H "X-IBM-Client-Id: ${appConClientID}" \ 
    -H "authorization: Bearer ${appConToken}" 

Creating an Integration Runtime Using the Configuration

For more information on creating an integration runtime, see the creating an integration runtime documentation.

Now that we have a configuration, we can create an integration runtime that uses the configuration like so:

irBody=’ 
    { 
        "metadata": { 
            "name": “http-echo-service" 
        }, 
        "spec": { 
            "template": { 
            "spec": { 
                "containers": [ 
                { 
                    "name": "runtime" 
                } 
                ] 
            } 
            }, 
            "barURL": [ 
                "https://github.com/<your GitHub org>/<your repo with Bar files in>/raw/main/<your BAR file name>.bar" 
            ], 
            "configurations": [ 
                "my-github-configuration" 
            ], 
            "version": "12.0", 
            "replicas": 1 
        } 
    }’ 
  

    curl -X POST https://${appConEndpoint}/api/v1/integration-runtimes \ 
    -H "x-ibm-instance-id: ${appConInstanceID}" \ 
    -H "Content-Type: application/json" \ 
    -H "Accept: application/json" \ 
    -H "X-IBM-Client-Id: ${appConClientID}" \ 
    -H "authorization: Bearer ${appConToken}" \ 
    -d "${irBody}" 

Use the "spec" field to shape your resource. For more information, see the documentation.
Note that we prevent the use of resource names that have certain prefixes in their name; e.g., "default-integration-runtime" (nor do we allow you to get, retrieve, create again, or delete it).
You can also see this integration runtime running and using the configuration in the App Connect Dashboard.

If you click to edit the integration runtime, you can see the configuration that is in use. In my case, I am using my own GitHub repository so I would see this:

Once the integration runtime has started successfully, you will be able to invoke your flow as you would any other flow in App Connect.

Invoking the Endpoint

This depends on the flow that's defined in the BAR file that you've used. In my example, it is a simple HTTP echo service, and I can use the following cURL command to invoke it and receive a response. Consult the App Connect documentation for how you would retrieve the endpoint to use in this case.

This request:
curl -X POST https://http-echo-service-https-<my App Connect endpoint which has my instance ID in>/Echo

Gave me this response:
<Echo><DateStamp>2023-08-07T13:04:13.143955Z</DateStamp></Echo>

Part Two

At this point, we know how to use the API to create a couple of simple resources. What we have not yet covered is uploading a BAR file for use in a new integration runtime. We have not yet covered the editing or deleting of resources either.

Uploading a New BAR File

These instructions assume that you already have a BAR file. To learn how to create a BAR file, refer to the App Connect Enterprise documentation. For more information about what resources are supported in BAR files that you import to App Connect, see the supported resources in imported BAR files documentation. 

You can use the App Connect API to upload a BAR file like so:

curl -X PUT https://${appConEndpoint}/api/v1/bar-files/TestBlogAPI \ 
    -H "x-ibm-instance-id: ${appConInstanceID}" \ 
    -H "Content-Type: application/octet-stream" \ 
    -H "Accept: application/json" \ 
    -H "X-IBM-Client-Id: ${appConClientID}" \ 
    -H "authorization: Bearer ${appConToken}" \ 
    --data-binary @/Users/adam/Downloads/TestBlogAPI.bar 

Notice the use of "--data-binary" here in order to prevent the BAR file from being unusable once uploaded. It is important to note that at the time of this post, the validation of the BAR file occurs when it is used by an integration runtime.

In my case, I have downloaded the BAR file from my GitHub repository. You don’t need to include ".bar" in the path for the API call, either.

If successful, you will be able to see this BAR file in the App Connect Dashboard.

Also, in the HTTP response, you will see the location of this BAR URL on the App Connect content server. It will be of the form:

{"name":"TestBlogAPI.bar","url":"https://dataplane-api-dash.appconnect:3443/v1/ac0ikbdsupj/directories/TestBlogAPI?" 

Important: you will need to use the "url" part of this, in your next command in order to have the integration runtime use this BAR file.

Creating a New Integration Runtime That Uses the New Bar File

irBody=’ 
    { 
        "metadata": { 
            "name": "second-ir-using-bar" 
        }, 
        "spec": { 
            "template": { 
            "spec": { 
                "containers": [ 
                { 
                    "name": "runtime" 
                } 
                ] 
            } 
            }, 
            "barURL": [ 
                "the exact URL from the previous step – including the question mark" 
            ], 
            "version": "12.0", 
            "replicas": 1 
        } 
    }’ 
curl -X POST https://${appConEndpoint}/api/v1/integration-runtimes \ 
    -H "x-ibm-instance-id: ${appConInstanceID}" \ 
    -H "Content-Type: application/json" \ 
    -H "Accept: application/json" \ 
    -H "X-IBM-Client-Id: ${appConClientID}" \ 
    -H "authorization: Bearer ${appConToken}" \ 
    -d "${irBody}" 

The key difference here is the removal of the configurations section and the difference in barURL.
On success, you should be able to see this integration runtime in the App Connect Dashboard.

Updating the First Integration Runtime To Use This Bar File Instead

In my example, I now have two integration runtimes that use the same BAR file because I used the one from my GitHub repository.

Let’s assume that I want to:

• Keep the first integration runtime
• Have it use this BAR file that I’ve uploaded using the API (instead of pulling from GitHub)
• Delete the second integration runtime

We can do this like so:

irBody=’ 
    { 
        "metadata": { 
            "name": "http-echo-service" 
        }, 
        "spec": { 
            “template": { 
            "spec": { 
                "containers": [ 
                { 
                    "name": "runtime" 
                } 
                ] 
            } 
            }, 
            "barURL": [ 
                "the exact URL from earlier – including the question mark" 
            ], 
            "version": "12.0", 
            "replicas": 1 
        } 
    }’ 
curl -X PUT https://${appConEndpoint}/api/v1/integration-runtimes/http-echo-service \ 
    -H "x-ibm-instance-id: ${appConInstanceID}" \ 
    -H "Content-Type: application/json" \ 
    -H "Accept: application/json" \ 
    -H "X-IBM-Client-Id: ${appConClientID}" \ 
    -H "authorization: Bearer ${appConToken}" \ 
    -d "${irBody}" 

The BAR URL differs and we no longer need to provide a configurations section, because no authorization is required to access a particular GitHub repository.

On success, you will again be able to see this integration runtime in the App Connect Dashboard.

Cleaning Up

Each resource can be cleaned up programmatically through its appropriate delete HTTP request API calls. The order in which you perform these operations doesn't matter.

To delete the configuration created in this example:

curl -X DELETE https://${appConEndpoint}/api/v1/configurations/my-github-configuration\ 
        -H "x-ibm-instance-id: ${appConInstanceID}" \ 
        -H "Content-Type: application/json" \ 
        -H "Accept: application/json" \ 
        -H "X-IBM-Client-Id: ${appConClientID}" \ 
        -H "authorization: Bearer ${appConToken}"   

To delete the BAR file created in this example:

curl -X DELETE https://${appConEndpoint}/api/v1/bar-files/TestBlogAPI \ 
        -H "x-ibm-instance-id: ${appConInstanceID}" \ 
        -H "Content-Type: application/json" \ 
        -H "Accept: application/json" \ 
        -H "X-IBM-Client-Id: ${appConClientID}" \ 
        -H "authorization: Bearer ${appConToken}" 

To delete both integration runtimes created in this example (although if you were following my commands, you should only have the first one):

curl -X DELETE https://${appConEndpoint}/api/v1/integration-runtimes/http-echo-service \ 
        -H "x-ibm-instance-id: ${appConInstanceID}" \ 
        -H "Content-Type: application/json" \ 
        -H "Accept: application/json" \ 
        -H "X-IBM-Client-Id: ${appConClientID}" \ 
        -H "authorization: Bearer ${appConToken}" 
 

curl -X DELETE https://${appConEndpoint}/api/v1/integration-runtimes/second-ir-using-bar \ 
        -H "x-ibm-instance-id: ${appConInstanceID}" \ 
        -H "Content-Type: application/json" \ 
        -H "Accept: application/json" \ 
        -H "X-IBM-Client-Id: ${appConClientID}" \ 
        -H "authorization: Bearer ${appConToken}" 

Conclusion

Using the public API, you can programmatically create resources for App Connect as you see fit (within the limits we define). The API provides an alternative to using the App Connect Dashboard, although you will be able to see changes in the Dashboard that you've made through the API. The public API provides equivalent functionality to the Dashboard only, and not to the App Connect Designer or App Connect Enterprise Toolkit. 

This example has demonstrated a broad range of features but more intricate scenarios using different connectors and flows can be explored.