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'"
}'
JWT=$(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 ${JWT}
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), which I will be setting and using in the cURL commands with:
export appConToken=<the App Connect authentication token>
-
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 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 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.
Now that we have a configuration, we can create an integration runtime that uses the configuration like so:
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}" \
Use the "spec" field to shape your resource. For more information, see the documentation.
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 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.
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: doing something a little more advanced…
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.
You will also, in the HTTP response, 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
"name": "second-ir-using-bar"
"the exact URL from the previous step – including the question mark"
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}" \
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.
"name": "http-echo-service"
"the exact URL from earlier – including the question mark"
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}" \
The BAR URL differs and we no longer need to provide a configurations section, because no authorisation 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 . 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}"
Summary and questions
We covered using the API to create, edit, and delete resources, while observing the results, but you probably have more questions than answers at this point. Here are a few that I think you might be thinking of…
Where can I submit feedback or enhancement requests?
Where do I submit bug reports?
We're sad that you've found one but happy to help: see the App Connect support section.
Can I take an integration runtime from the Dashboard view and create one just like it?
Yes, but be sure to modify the "configurations" section as appropriate. We add a few for you whenever you make an integration runtime, so unless you want to refer to your own created configuration, leave that section blank.
How big can my integration runtime be?
You can have a maximum of 50 integration runtimes per namespace, with a maximum of six replicas each, and you can't exceed the CPU and memory amounts for your instance.
What are the rate limits?
The cost is based on your resource usage, not the API calls themselves. Avoid making more resources than you need and try to keep only the ones you are using.
Is there a collection somewhere I can use?
Not at this time but we do think it would be useful. Having the API document available should satisfy your needs…
Conclusion
With our public APIs now available, you can programmatically create resources for App Connect as you see fit (within the limits we define). What I have highlighted does not cover a more intricate scenario using different connectors and flows.
Think about how you might combine these features in order to achieve your goals.
We look forward to hearing your feedback and please do not hesitate to let us know what you think!
#automation-featured-area-1
#Featured-area-2