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.
programmatically do the following tasks:
-
A worked example that creates, edits, and deletes resources, using 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
At the time of this post, you can use this feature in:
-
North Virginia
-
Frankfurt
-
London
-
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.
-
Once you have the client ID, client secret, and API key, these are not expected to . The current expiry date at the time of this post is two years.
-
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.
s. 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.
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.
In part two we will then do something more advanced that involves:
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.
-
Your App Connect instance ID, which I will be setting and using in the cURL commands with:
export =<the instance ID>
-
Your App Connect client ID, which I will be setting and using in the cURL commands with
export appConClientID=<the client ID>
-
Your App Connect authentication token (that you made earlier and lasts twelve hours) - i named it appConToken
-
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 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.
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"
encodedAuthData=$(echo -e "${gitHubAuthData}" | base64)
\"name\": \"my-github-configuration\"
\"data\": \"${encodedAuthData}\",
\"description\": \"Authentication for GitHub\",
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" \