API bindings

Introduction

API bindings are externalized specifications created per API dependency. They can be used to store API-related information that may be stage-dependent. Let's say you want to integrate an external API that provides two endpoints, one for development and one for production use. And this API requires an API key to be sent with every request.

While development, you want to connect to the development endpoint of this API but when moving to production you will want to use the production endpoint of it. To ease that up, you can create API bindings and put this information in two places. The binding you need while development is called a DEV binding and you can create it inside Solution Designer (by default they are only allowed on DEV stages). To do so, you go to the Integration Namespace you want ot use for interacting with this API (or create a new namespace) and create an API dependency. There you will find an input field where you can place your information as JSON formatted key/value pairs.

Example binding:

{
  "url": "http://example.com/dev"
}

Attention: Please be aware, that all information entered into DEV bindings will go into the Git repository! To prevent this, you can instead create an API binding for the same purpose, since they get stored as OpenShift secrets inside the cluster.

Now that you created an API dependency for this namespace with an API dependency attached to it, you have access to this information while implementing this namespace. After you deployed your solution to a project you can log in to this project with the Solution CLI. The Solution Framework now provides you with the information by calling

// load the bindings
const mybindings = await this.apiBindings.<name-of-the-api-dependency>();

// load binding value
const url = mybindings.url;

inside an implementation file (e.g. of a service) inside that Integration Namespace. This would assign the value http://example.com/dev to url.

Currently, only the following default parameters can be accessed with this syntax:

url
ca_cert
k5_propagate_security_token

If you want to use custom parameters you can access them as followed:

const myparam = mybindings['myparam'];

Applying stage-dependent values

Now if you wanted to move to production, you may have different information required, e.g. an API key. Since you want this information only to be applied for the deployment on the PROD stage you can create a dedicated API binding for this project. This will replace the DEV binding information with this specific information.

Tip: API bindings can be used to provide different information for different stages/projects. Don't forget to re-deploy the solution to have access to any updated or appended key/value pairs.

To create an API binding, you have to use the Configuration Management API under Solution Configuration and create a new Solution Configuration.

Tip: As long as not configured otherwise, the default URL where you can find the Configuration Management Swagger UI is built like this:

https://ssob-config.<domain>

The exact URL can be found within the route named k5-configuration-management. It can be easily retrieved by executing

oc get route k5-configuration-management -n <namespace>

whereby <namespace> points to the namespace, where the Solution Designer and Hub are installed (e.g. zen).

Managing API bindings

API bindings are created as Solution Configurations. Therefore, you can use the same operations to query them. Each API binding results in an OpenShift secret and will be stored and handled as an OpenShift secret.

Get all Solution configurations of a project

Use GET method Get all Solution Configurations in the Swagger UI or

curl -X GET "{your-hostname}/api/cfg/v1/runtimes/{runtimeName}/solutions/{solutionAcronym}/configurations" -H "accept: application/json" -H  "Authorization: Bearer {BearerToken}"

Get a specific Solution Configuration of a project

Use GET method Get a specific Solution Configuration in the Swagger UI or

curl -X GET "https://{your-hostname}/api/cfg/v1/runtimes/{runtimeName}/solutions/{solutionAcronym}/configurations/{configurationName}" -H  "accept: text/plain" -H "Authorization: Bearer {BearerToken}"

Request Parameters:


Parameter	Type	Description
runtimeName	path parameter (String)	The name of the specific k5-project, e.g. cpd-runtime-default
solutionAcronym	path parameter (String)	The acronym of a solution, e.g. ORDERS
configurationName	path parameter (String)	The name of the specific Solution Configuration.

Create or edit API bindings

Use POST method Create or update a specific Solution Configuration in the Swagger UI or

curl -X POST "https://{your-hostname}/api/cfg/v1/runtimes/{runtimeName}/solutions/{solutionAcronym}/configurations/{configurationName}" -H "accept: */*" -H "Authorization: Bearer {BearerToken}" -H  "Content-Type: text/plain" -d ""


Parameter	Type	Description
configurationName	path parameter (String)	The name of the configuration - must be the integration namespace's acronym concatenated by a dash with the API-dependency name in Solution Designer (e.g. acronym-dependencyname)
runtimeName	path parameter (String)	The name of the deployment target, e.g. cpd-runtime-default.
solutionAcronym	path parameter (String)	Acronym (in capitals) of the specific project/component that uses the dependency, e.g. ORDERS.
configurationValue	body parameter (JSON)	The binding information needed to call the dependency.

Tip: You might not need a specific API binding if the named dependency is also developed with IBM Financial Services Workbench , and you marked "Local Lookup" while adding the API dependency in your solution. If the JSON Web Token (JWT) that is used in a solution should be forwarded to call the API dependency, the following must be included in the configuration value (as JSON): "k5_propagate_security_token": true

Delete API bindings

Use DELETE method Delete a specific Solution Configuration in the Swagger UI or

curl -X DELETE "https://{your-hostname}/api/cfg/v1/runtimes/{runtimeName}/solutions/{solutionAcronym}/configurations/{configurationName}" -H  "accept: text/plain" -H "Authorization: Bearer {BearerToken}"

Request Parameters:


Parameter	Type	Description
runtimeName	path parameter (String)	The name of the specific k5-project, e.g. cpd-runtime-default
solutionAcronym	path parameter (String)	The acronym of a solution, e.g. ORDERS
configurationName	path parameter (String)	The name of the specific Solution Configuration.

Examples

Call an internal API (built with FSW)

In this example, there is a service project with an acronym of "MYPROJ" that contains an integration namespace with the prefix "extdat". This integration namespace has an API dependency modelled with an identifier "querydata" to query data from the REST API ("v1") of another service project with an acronym of "CNR". Both service projects have been built with IBM Financial Services Workbench and have the same deployment target "cpd-runtime-test" configured. The service project "CNR" has to be deployed already on that deployment target to be called by "MYPROJ".

Since both projects are built with IBM Financial Services Workbench and running on the same target, we also want to pass on the JWT token automatically. To do so, we also add k5_propagate_security_token to the binding and set its value to true.

Now to actually make use of the methods to call that REST API, you need to create an API binding as described below:

runtimeName            cpd-runtime-test
solutionAcronym        MYPROJ
configurationName      extdat-querydata
Request body           {
                         "url": "https://cpd-runtime-test.apps.openshift-host.cloud/cnr/api/v1",
                         "k5_propagate_security_token": true
                       }

Call an external API

Now if the above-mentioned service project needs to query data from an external REST API (e.g., an ML-Service) that is not running in the same deployment target, you would create another API dependency inside the same integration namespace with an identifier of "callexternalapi". Querying this external REST API requires passing credentials with each request. These can also be added to the API binding using custom fields.

Note: The custom fields depend on the REST API you want to query. Please be aware, that none of the custom fields get auto-mapped to any part of the HTTP request. But you have access to these key/value pairs while implementing without having to care about their values since these can be configured from outside the project. This allows you to map any custom value to the required part of the request, e.g. headers, parameters or even the request body.

The required API binding can be created as described below:

runtimeName            cpd-runtime-test
solutionAcronym        MYPROJ
configuratioName       extdat-callexternalapi
Request body           {
                         "url": "https://mlpattern.123.456.789.10.example.io",
                         "user": "userName",
                         "password": "passWord"
                       }

Attention: Any change to the API binding will only be applied to the projects after a new deployment.