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 here will go into the Git repository!

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 login to this project with the FSS CLI tool. 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 -n <namespace>

, whereby points to the namespace, where the Solution Hub is installed.

Managing API Bindings

API bindings are stored as Solution Configurations. Therefore, you can use the same operations to query them.

Get all Solution Configurations of a solution

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 solution

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. acr-example)
runtimeName	path parameter (String)	The name of the specific k5-project, e.g. cpd-runtime-default.
solutionAcronym	path parameter (String)	Acronym of the specific solution 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)

API binding to call an API dependency named "dependency" from within the integration namespace with the acronym "ns" of a solution with the acronym "calling" (which has also been developed with Financial Services Workbench).

runtimeName            cpd-runtime-test
solutionAcronym        calling
configurationName      ns-dependency
Request body           {
                         "url": "https://cpd-runtime-test.apps.openshift-host.cloud/dependency/api/v1",
                         "k5_propagate_security_token": true
                       }

Call an external API

API binding to call a foreign API dependency (e.g. a ML-Service)

runtimeName            cpd-runtime-test
solutionAcronym        calling
configuratioName       ns-dependency
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 solutions after a new deployment.