To get the access token you will need to use your Keycloak username and password with our <baseURL>/api/v1/tokens POST endpoint. You will need the baseURL for the API, which you can get from the OpenShift Console UI by looking at the right-hand side of the Dashboard instance Details page under the API heading:
On OpenShift, you can also get this value using oc describe <dashboardName>; use the value under Admin API URL in the Status section.
On Kubernetes, the baseURL is https://<dashboardHostPrefix>.<ingress_subdomain> using the values you've set for the prefix and subdomain in your Ingress definition for the API. See our documentation for examples on creating Ingress definitions for the Dashboard API.
You then need to Base64 encode the username and password for the Keycloak user with the dashboard-admin role, for example:
encodedLogin=$(echo -n 'testuser:myT0pSecretPassw0rd' | base64)
and then use the result when calling the endpoint:
curl -X POST https://baseURL/api/v1/tokens -H "Authorization: Basic ${encodedLogin}"
This will give you a response in the following format:
{
"accessToken": "tokenValue"
}
The tokenValue is a Keycloak Offline Access Token in the format of a JSON Web Token (JWT). By default this will only expire when not used for 30 days. This period can be modified in the Realm settings in the Keycloak Administration UI, where sessions can also be logged out to revoke a user's API access.
This call to the API is being made on a command line using curl, as will other commands below, but they could also be done using a UI-based API tool:
You could use a UI-based tool, a command line tool like curl, or construct calls in any programming language that lets you build HTTP requests.
Once you have the token, you need to supply an Authorization header in your requests to the API, using the authorization type of Bearer, for example in curl:
-H "authorization: Bearer tokenValue"
OpenAPI Specification
If you want to see all the paths you can call, what methods they support, what body to supply, and the expected responses, you can use the OpenAPI specification for the API. You can see the complete specification in our documentation. You can also get the specification by going to https://<baseURL>/api/v1/openapispec in your browser or using the tools mentioned above to call this URL. This version will include the baseURL and security settings to match those on your instance so you can use the specification directly in a tool, including the Swagger Editor.
Calling the API
We can start off with a simple request to the API to show everything is working. This is particularly useful if you have authorization and authentication enabled to show you have a valid token:
-H "Accept: application/json" \
-H "authorization: Bearer tokenValue"
This will show you all the BAR files which have been uploaded to the Dashboard, either via the App Connect Dashboard UI or the API. This will return something like:
{
"barFiles": [
{
"name": "CustomerDatabaseV1.bar",
"url": "https://dashboard.namespace:3443/v1/directories/CustomerDatabaseV1?abc123-defg-45678-hijkl"
},
{
"name": "HTTPEchoHost.bar",
"url": "https://dashboard.namespace:3443/v1/directories/HTTPEchoHost?abc123-defg-45678-hijkl"
}
}
Uploading a new BAR file
If you want to push a BAR file to the Dashboard's built-in content server (rather than using an external repository) you can do now so using the API.
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. You can perform the upload on the command line like this:
curl -X PUT https://baseURL/api/v1/bar-files/MyIntegration \
-H "Accept: application/json" \
-H "Content-Type: application/octet-stream" \
-H "authorization: Bearer tokenValue" \
--data-binary @/path/to/file/MyIntegration.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 the validation of the BAR file only occurs when it is used by an Integration Runtime.
If successful, you will be able to see this BAR file in the App Connect Dashboard UI, or by following the "Calling the API" section again.
You will also, in the HTTP response, see the URL for the BAR file, which you can then use when creating an Integration Runtime:
{
"name": "MyIntegration.bar",
"url": "https://dashboard.namespace:3443/v1/directories/MyIntegration?abc123-defg-45678-hijkl"
}
Creating a new Integration Runtime that uses the new BAR file
The following is an example Integration Runtime that you can create using the newly uploaded BAR file via the API. First set up the properties for the Integration Runtime in JSON, similar to how you would in the YAML editor in the OpenShift UI or the App Connect Dashboard UI
irBody='
{
"metadata": {
"name": "ir-api"
},
"spec": {
"barURL": [
"https://dashboard.namespace:3443/v1/directories/MyIntegration?abc123-defg-45678-hijkl"
],
"license": {
"accept": true,
"license": "L-QECF-MBXVLU",
"use": "AppConnectEnterpriseProduction"
},
"replicas": 1,
"version": "12.0"
}
}'
where the spec.barURL value comes from the url in the response above when uploading the BAR file. spec.license.license will also need to be set appropriately for the version of the Integration Runtime you are creating.
Then run the following command:
curl -X POST https://baseURL/api/v1/integration-runtimes \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "authorization: Bearer tokenValue" \
-d "${irBody}"
On success, you should be able to see this Integration Runtime in the App Connect Dashboard UI, in the OpenShift Console UI or via another API call. It is now a running integration with message flows processing data, and you can interact with any endpoints you have set up.
Updating the Integration Runtime
If you want to update the Integration Runtime then you can also do this via the API. Again you need a definition of the Integration Runtime in JSON, this time with the modified parameters:
irNewBody='
{
"spec": {
"barURL": [
"https://dashboard.namespace:3443/v1/directories/MyIntegration?abc123-defg-45678-hijkl",
"https://dashboard.namespace:3443/v1/directories/NewIntegration?abc123-defg-45678-hijkl"
],
"license": {
"accept": true,
"license": "L-QECF-MBXVLU",
"use": "AppConnectEnterpriseProduction"
},
"replicas": 2,
"version": "12.0"
}
}'
Note that you need the entire spec section for the updated Integration Runtime, and not just the changes. Here the barURL has been changed to point at an additional BAR file, and replicas has been increased from 1 to 2.
Then run the following command:
curl -X PUT https://baseURL/api/v1/integration-runtimes/ir-api \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "authorization: Bearer tokenValue" \
-d "${irNewBody}"
This will modify the existing Integration Runtime and the deployment will create new pods reflecting these changes.
Cleaning up
Each resource can be cleaned up programmatically through its appropriate DELETE HTTP request . You can use:
curl -X DELETE https://baseURL/api/v1/integration-runtimes/ir-api \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "authorization: Bearer tokenValue"
to first delete the Integration Runtime, and then:
curl -X DELETE https://baseURL/api/v1/bar-files/MyIntegration \
-H "Accept: application/json" \
-H "Content-Type: application/octet-stream" \
-H "authorization: Bearer tokenValue"
to delete the BAR file from the Dashboard's content server. You cannot delete a BAR file which is currently being used by an Integration Runtime.
Conclusion
With this new API for IBM App Connect in containers, you can programmatically create resources for your App Connect deployments, removing the requirement to use the UI for certain tasks. This offers new opportunities when building continuous integration and continuous delivery (CI/CD) pipelines.