API Dependencies

By uploading an API specification either as OpenAPI 3 file (.yaml) or as Swagger file (.json), Solution Designer will create methods for each operation available in the API specification that can be used while implementing integration services. The uploaded API specification will be placed inside the Git repository of the solution and is available to the developer while implementation.

Example implementation:

You have a solution with an integration namespace called "Customer Need Registration". The integration namespace's acronym is "cnr". Inside this namespace you have created an integration service called "AcceptOffer" and this service should call another API. You also created an API dependency with the name "cnrdependency" inside this integration namespace and uploaded a valid OpenAPI3 or Swagger file.

This API provides the operation "acceptOffer" (amongst others) that will be called in this example.

Now to implement this service you can do the following inside the implementation file of this service (e.g., src-impl/integration/cnr/services/AcceptOffer.ts):

import { services } from 'solution-framework';

export default class extends services.cnr_AcceptOffer {

  public async execute(): Promise<void> {
    const log = this.util.log;
    log.debug('cnr_AcceptOffer.execute()');

    // Get the values for the request parameters from the input
    const {customerNeed_id, customer_ID, finPropId} = this.input;

    // Use the created API operations
    const response = await this.apis.cnrdependency.acceptOffer({customerNeed_id: customerNeed_id},{customerID_query: customer_ID,finPropId: finPropId});

...

DEV bindings are optional specifications created per API dependency. This means that the DEV binding only lives as a part of the API dependency and shares its life-cycle. It is assigned a unique name internally and will not receive an identifier within Solution Designer.

You can use DEV bindings to append important information about the API you want to integrate and store it inside the Integration Namespace. This may be URLs, certificates, token, credentials or anything else that you want to have at hand when implementing your requests to another REST API. These bindings only consist of key/value pairs in JSON notation.

Example of a binding:

{
    "url": "https://example.com"
}

Entering this key/value pair into the DEV binding section of an API dependency will provide the value of url in the solution framework (SDK) when implementing. They will be accessible by typing this.apiBindings.<integration namespace acronym>. inside an implementation file of an integration namespace.

Example implementation:

You have a solution with an integration namespace called "Customer Need Registration". The integration namespace's acronym is "cnr". Inside this namespace you have created an integration service called "AcceptOffer" and this service should call another API. You also created an API dependency with the name "cnrdependency" inside this integration namespace and added the information to the DEV binding as stated in the example above.

Now to implement this service you can do the following inside the implementation file of this service (e.g., src-impl/integration/cnr/services/AcceptOffer.ts):

import { services } from 'solution-framework';

export default class extends services.cnr_AcceptOffer {

  public async execute(): Promise<void> {
    const log = this.util.log;
    log.debug('cnr_AcceptOffer.execute()');

    // Retrieve the API binding information (async call)
    const binding = await this.apiBindings.getcnrdependency();

    // Built-in parameters (url, ca_cert, k5_propagate_security_token) can be retrieved like this
    const url = binding.url;

    // the value of url will be 'https.//example.com'

    ...

This will work for the following pre-defined parameters:

• url - Used to pass the URL of the API to the SDK and can be overwritten with stage-dependent values by adding API bindings for the different stages.

• k5-propagate-jwt-token - If set to true, the JSON Web Token (JWT) used in your solution will be forwarded to call the API dependency.

• ca-cert - By using this option no additional binding information is necessary. The URL of the dependency will be changed dynamically depending on the deployment namespace. Also the JSON Web Token (JWT) will be forwarded and used to call the API dependency. This option should only be used for API dependencies that have been designed and implemented with Financial Services Workbench and are deployed within the same projects/namespaces.

If you want to use your own custom parameters, you just have to add them to your DEV binding in the same manner.

{
    "my-custom-key": "A32k-9IFKl123",
    "another-key": 123456
}

The only difference is the way to call them:

...

    // Retrieve the API binding information (async call)
    const binding = await this.apiBindings.getCnrdependency();

    // Now call the binding parameter 'my-custom-key' like this
    const mycustomkey = binding['my-custom-key'];

...

When you want to move your solution from development stage to a production stage you can then simply exchange the information of the DEV binding with a dedicated API binding for this stage. Externalizing those binding information must be done with the Configuration Management inside Solution Hub. API bindings specified there will always overwrite the ones specified in Solution Designer and can differ across stages and/or Solution Envoys.

Can be used for API dependencies that also have been developed with Financial Services Workbench and allows calling this dependencies without the need to provide additional binding information. This makes it easy and convenient to call operations provided by external APIs since the URL of the dependency will be changed dynamically and the JWT will be automatically forwarded.