Accessing the API for IBM App Connect in containers

To make an API call to the IBM® App Connect API, provide the base URL of the API and an operation path in your request. If Keycloak is configured for your App Connect Dashboard instance, also provide authentication credentials (in the form of an access token) in the request.

The following sections provide more information about accessing the API.

Locating the base URL for the API endpoints
Generating an access token
Making calls to the API
Viewing and downloading the API definition as an OpenAPI document

Locating the base URL for the API endpoints

A unique API base URL is generated for each App Connect Dashboard instance that you deploy with a spec.api.enabled value of true. This setting enables the IBM App Connect API and allows you to interact with an API server (which runs in a container) to administer the Dashboard's resources. For information about enabling the API during deployment, see App Connect Dashboard reference: Creating an instance. To enable the API in an existing 12.0.12.2-r1 or later Dashboard instance, see App Connect Dashboard reference: Updating the custom resource settings for an instance.

The base URL for an API endpoint is generated in the following format:

https://dashboardName-api-namespaceName.clusterHostname

Where:

dashboardName is the name of the Dashboard instance.
namespaceName is the namespace where the Dashboard is deployed.
clusterHostname is the hostname of the cluster.

Example:
https://db-fd-aceccdash-rc1-api-ace-fiona.apps.acecc-cd-414-amd64.abc.com

Note: If you are working in a Kubernetes environment, you will need to expose the API to external traffic by creating an ingress route for the base URL in the following format:

https://<dashboardHostPrefix>.<ingress_subdomain>

To locate the base URL for an API endpoint, complete either of the following steps:

Red Hat® OpenShift® web console:
1. From a browser window, log in to the Red Hat OpenShift Container Platform web console. Ensure that you are in the Administrator perspective .
2. From the navigation, click Operators > Installed Operators.
3. If required, select the namespace (project) in which you installed the IBM App Connect Operator.
4. From the Installed Operators page, click IBM App Connect.
5. Click the Dashboard tab on the Operator details page.
6. From the list of deployed Dashboard instances, click your Dashboard name to view information about its definition and status.
  On the Details tab, locate the API field, which displays the base URL for the API server that is reserved for the Dashboard instance. This URL, and other displayed URLs, are shown only after the Dashboard is successfully deployed. You can also locate the URL under Networking > Routes in the console navigation.

Red Hat OpenShift or Kubernetes CLI:

From the command line, log in to your cluster.
- On Red Hat OpenShift, use the oc login command.
- In a Kubernetes environment, use the command for your environment. For example, if you are using an Azure Kubernetes Service (AKS) cluster, use the Azure CLI (az).

Run the following command to list the App Connect Dashboard instances that are deployed in your namespace.

oc get dashboards -n namespace

kubectl get dashboards -n namespace

In Dashboard instances at version 12.0.12.3-r1 or later, the output includes an

API
URL

value that displays the base URL for the API server that is reserved for the Dashboard instance, as shown in the following example.

NAME                 RESOLVEDVERSION   REPLICAS   CUSTOMIMAGES   STATUS   UI URL                                                                     API URL                                                                     KEYCLOAK URL                                                         AGE
db-fd-aceccdash-rc1  12.0.12.3-r1      1          false          Ready    https://db-fd-aceccdash-rc1-ui-ace-fiona.apps.acecc-cd-414-amd64.abc.com   https://db-fd-aceccdash-rc1-api-ace-fiona.apps.acecc-cd-414-amd64.abc.com                                                                        10h
db-fd-cp4i-rc1       12.0.12.3-r1      1          false          Ready    https://db-fd-cp4i-rc1-ui-ace-fiona.apps.acecc-cd-414-amd64.abc.com        https://db-fd-cp4i-rc1-api-ace-fiona.apps.acecc-cd-414-amd64.abc.com        https://keycloak-ibm-common-services.apps.acecc-cd-414-amd64.abc.com  8h

Copy and save the API URL value for later use.

In Dashboard instances at version 12.0.12.2-r1, the output is similar to the following example:

NAME                  RESOLVEDVERSION   REPLICAS   CUSTOMIMAGES   STATUS   URL                                                                        KEYCLOAKURL                                                            AGE
db-fd-aceccdash-rc1   12.0.12.2-r1      1          false          Ready    https://db-fd-aceccdash-rc1-ui-ace-fiona.apps.acecc-cd-414-amd64.abc.com                                                                          10h
db-fd-cp4i-rc1        12.0.12.2-r1      1          false          Ready    https://db-fd-cp4i-rc1-ui-ace-fiona.apps.acecc-cd-414-amd64.abc.com        https://keycloak-ibm-common-services.apps.acecc-cd-414-amd64.abc.com   8h

Run the following command to view details about your specific Dashboard instance.

oc describe dashboard dashboardName

kubectl describe dashboard dashboardName

In the output, locate the Status.Endpoints section and look for the Uri value that is associated with Name: api and Type: API. The following example shows a sample command and sample output on Red Hat OpenShift.

C:\Windows\System32>oc describe dashboard db-fd-aceccdash-rc1
Name:         db-fd-aceccdash-rc1
Namespace:    ace-fiona
Labels:       backup.appconnect.ibm.com/component=dashboard
Annotations:  <none>
API Version:  appconnect.ibm.com/v1beta1
Kind:         Dashboard
...
Spec:
  API:
    Enabled:  true
  Authentication:
    Integration Keycloak:
      Enabled:  true
  Authorization:
    Integration Keycloak:
      Enabled:   true
  Display Mode:  IntegrationRuntimes
  License:
    Accept:   true
    License:  L-QECF-MBXVLU
    Use:      CloudPakForIntegrationNonProduction
  ...
Status:
  Admin API URL:  https://db-fd-aceccdash-rc1-api-ace-fiona.apps.acecc-cd-414-amd64.abc.com
  Admin Ui URL:   https://db-fd-aceccdash-rc1-ui-ace-fiona.apps.acecc-cd-414-amd64.abc.com
  Conditions:
    ...
  Custom Images:           false
  Endpoints:
    Name:  ui
    Type:  UI
    Uri:   https://db-fd-aceccdash-rc1-ui-ace-fiona.apps.acecc-cd-414-amd64.abc.com
    Name:           keycloakui
    Type:           UI
    Uri:            https://keycloak-ibm-common-services.apps.acecc-cd-414-amd64.abc.com
    Name:  api
    Type:  API
    Uri:   https://db-fd-aceccdash-rc1-api-ace-fiona.apps.acecc-cd-414-amd64.abc.com
  Keycloak Ui URL:  https://keycloak-ibm-common-services.apps.acecc-cd-414-amd64.abc.com
  ...

Copy and save the Uri value for the API for later use.

Note: If you are working in a Kubernetes environment, you must now create an ingress definition for the API (with an externally-reachable URL), to make its internal service publicly available. For more information, see Manually creating ingress definitions for external access to your IBM App Connect instances in Kubernetes environments.

Generating an access token

If Keycloak is enabled and configured in your environment, you need an access token to authenticate to the API and make API calls. Tokens support authenticated requests without the need to embed user credentials in every call.

The IBM App Connect API definition includes a Token resource (or object) with a create operation, which you must use to generate access tokens. This operation uses a POST method on path /api/v1/tokens. The access token that is returned in the response is a Keycloak offline token, which is issued as a long-lived token. The access token expires after 30 days of inactivity after which you need to generate a new token.

To generate an access token, use a tool like cURL or Postman to send the POST request for a token object to the API. You need to provide the following information in the request:

The endpoint to which you are sending the POST request. The full URL of this endpoint is made up of these component parts:
- The base URL of the API
- The /api/v1/tokens operation path for the POST method
Construct the endpoint URL by appending the operation path to the API's base URL; for example:

https://db-fd-aceccdash-rc1-api-ace-fiona.apps.acecc-cd-414-amd64.abc.com/api/v1/tokens

Tip: If you copy the base URL of the API from the Red Hat OpenShift web console, a trailing forward slash (/) is appended to the URL. So, ensure that you delete this trailing forward slash before you append /api/v1/tokens.
Basic authentication credentials that specify the Keycloak username and password that you use to log in to the Dashboard.

The following example shows the endpoint URL and basic authentication credentials that are sent in the POST request from a UI-based client. The example also shows the access token that is returned in the response.

Details of a sample POST request within a UI-based tool and the generated access token in the response

The following example shows how you might structure a cURL command, which includes basic authentication credentials for the Dashboard, to get an access token.

Base64 encode the basic authentication credentials. (Depending on your operating system, you can use commands such as echo, base64, or certutil to Base64 encode this data.)
```
echo -n 'username:password' | base64
```
Example:
```
echo -n 'fd-testuser:myT0pSecretPassw0rd' | base64
```

In the cURL command, include the Base64-encoded value that was generated.

curl -X POST https://baseURL/api/v1/tokens -H 'Authorization: Basic base64EncodedValue'

Example:

curl -X POST https://db-fd-aceccdash-rc1-api-ace-fiona.apps.acecc-cd-414-amd64.abc.com/api/v1/tokens -H 'Authorization: Basic dGVzdHVzYpI6cGFzc3cwckQ'

If your POST request is successful and your credentials are confirmed, an access token is returned in the following format.

{
    "accessToken": "myAccessToken"
}

Making calls to the API

Before you begin to make API calls, determine whether you need an access token for authenticating to the API. For more information, see Access requirements for the API.

To review the available HTTP methods and operation paths in the API definition, see the IBM App Connect API documentation, which is presented in the Swagger UI. You can copy the operation paths from the Swagger UI by using the Copy to clipboard icon for any method.

To invoke any of the operations, supply the HTTP method, the full URL of the endpoint where the request should be sent, and a request body, if applicable. The full endpoint URL is constructed by appending the operation path to the base URL of the API.

For more information about the API, see Response codes and error handling and Rate limits.

Viewing and downloading the API definition as an OpenAPI document

You can view and download the IBM App Connect API definition as an OpenAPI document. The API definition conforms to the OpenAPI Specification Version 3.0, and defines all the resources and operations of the API. You do not need an access token to view or download the OpenAPI document.

To view and download the OpenAPI document, complete the following steps:

Use a browser window to view the OpenAPI document:
1. Copy the base URL of the API (https://dashboardName-api-namespaceName.clusterHostname) to a text editor.
2. Append /api/v1/openapispec to the base URL to construct the endpoint URL for the OpenAPI document; for example:
  https://db-fd-aceccdash-rc1-api-ace-fiona.apps.acecc-cd-414-amd64.abc.com/api/v1/openapispec
  
  Note: If you copy the base URL of the API from the Red Hat OpenShift web console, ensure that you delete the trailing forward slash (/) from the base URL before you append /api/v1/openapispec.
3. Paste the endpoint URL for the OpenAPI document into the address bar of a browser window. The content of the OpenAPI document is displayed. Depending on your browser, the content might automatically be structured in a pretty-print JSON format, or you might be allowed to switch to this format. The following example shows some sample JSON output in a browser window.
Download an OpenAPI document by saving it as a .json file in either of the following ways:
- Copy the JSON content in the browser to a text editor and then save it as a .json file.
- If applicable for your browser, right-click within the window and use the Save as option to save the JSON content as a .json file; for example, openapispec.json.