App Connect

 View Only

Introducing the App Connect Public API

By Adam Roberts posted Tue August 15, 2023 11:29 AM

  

We're pleased to announce the first release of the official App Connect public API.

Have you ever wanted to create App Connect resources programmatically, or provide your own monitoring and administration capabilities?

With our first release of the App Connect public API you can do exactly that if you have an App Connect subscription. 

Note that the information and documentation linked to here may change over time but this post serves as a good introduction for those looking to get started.  

This 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.

 

With the introduction of the API, you can now programmatically do 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.

What you can't do

  • At the time of this post, you can't perform Batch processing or create and administer switch servers. 

 

What this post includes

  • A worked example that creates, edits, and deletes resources, using Bash, with any hints and tips highlighted. 

  • Links to learn more, including how to see our OpenAPI document. 

  • Ideas for making the most out of this new capability. 

 

What this post doesn't include

  • Using the API outside of curls from within a terminal window. 

  • Building your own App Connect flow to be deployed – an example BAR file is used instead. 

  • More complex administrative tasks – look out for future blog posts in this area. 

 

Regions available

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.

Here is an example call to the tokens endpoint which assumes the user has already set the variables.

apiKeyBody='{
"apiKey": "'$appConAPIKey'"
}'

appConToken=$(curl -v -X POST ${appConEndpoint}/api/v1/tokens \
-H "x-ibm-instance-id: ${appConInstanceID}" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-IBM-Client-Id: ${appConClientID}" \
-H "X-IBM-Client-Secret: ${appConClientSecret}" \
-d "${apiKeyBody}")
echo ${appConToken}

Getting a new token will count towards your rate limit.

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.

In part one we are going to: 

  • 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 neccessary so App Connect can authenticate and pull in the BAR file from your repository.

  • Create an integration runtime that will use the configuration. 

  • Call the flow's endpoint that's running on our integration runtime. 

 

In part two we will then do something more advanced that involves:

  • Creating a new BAR file that contains a different flow from what is in the GitHub repository. 

  • Creating a new integration runtime that will run this BAR file. 

  • 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. This demonstrates a broad range of features, but not all of them, from our API. You will be able to see your changes in the App Connect Dashboard. For more details on each API, please refer to the appropriate App Connect documentation, including for each resource type. 

 

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> 

  1. Your App Connect client ID, which I will be setting and using in the cURL commands with 

export appConClientID=<the client ID> 

  1. Your App Connect authentication token (that you made earlier and lasts twelve hours) - i named it appConToken

  1. The App Connect endpoint (in my example, it will be exported with the full URL including https) 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 at 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 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 ${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 ${appConEndpoint}/api/v1/configurations \ 

    -H "x-ibm-instance-id: ${appConInstanceID}" \ 

    -H "Content-Type: application/json" \ 

    -H "Accept: application/json" \ 

    -H "X-IBM-Client-Id: ${