API dependency

The main purpose of an API dependency is to easily call an external REST API. It offers three main capabilities:

• Upload API specification

• DEV Binding

• Local Lookup

Creating an API dependency is not required to call a REST API. It is just a convenience functionality that you can use to make implementation easier. You can use the native capabilities to make HTTP calls too. Even if you create an API dependency you don't have to use all the capabilities. You can upload an API specification to get all the defined operations generated in the SDK or only use a DEV binding to store your own key/value pairs outside the implementation code and replace these values later for different deployment targets with API bindings.

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

Example implementation:

You have a service project with an integration namespace called "Customer Need Registration". This integration namespace's acronym is cnr. Inside this namespace you have created an integration service called "AcceptOffer" and this service should call another API. To do so, you also created an API dependency with the name cnrdependency inside this integration namespace and uploaded a valid OpenAPI 3 or Swagger 2.0 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.

Can be used for API dependencies to microservices that also have been developed with IBM Financial Services Workbench and allows calling these 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.

To create an API dependency in Solution Designer, open an integration namespace of your service project and click on the "General" tab and then click on "Add API dependency" button. Kindly fill in the required information as described below:

After creating an API dependency, you will be able to view all the details of the API dependency in the sidebar's API dependency details card. In case an API specification has been added to the API dependency, the General tab will show the API spec in a colored graphical view. You can switch to the detailed swagger view by clicking on the script button (left of trash button). You can use the search bar to filter by methods, tags and description.

You can edit the master data of an API dependency by using the Update API dependency button. The name of the API dependency cannot be changed. When editing the master data of an API dependency, you can update the API specification, DEV binding and Local lookup.

You can delete the API dependency by clicking on the trash button (left of Update API dependency button) in the General tab.

You will need to confirm the action before the selected API dependency is permanently deleted.