API dependencies

To create an API dependency in Solution Designer, open an integration namespace of your service project and click on the "Dependency" 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.

To create an API dependency based on another existing project, first you need to make sure that the modeled API you want to import is already committed to your repository then follow the following steps:

1. Fill in the 'Main Data' step and select "Choose from existing project" in "API Specification" field and click on button "Next".
2. In "Select Service Project" step you can see and select service project you want to import the API specification from. Note: Only Domain Service Projects are available to select.
3. In the step "Select API" you can see and select one of the modeled APIs of the choosen service project. Note: If the choosen service project contains only one modeled API, this is selected automatically and you will be guided to the next step.
4. The last step is "View API" step, and it displays the operations available of the selected API. And finally click on "Create" button to add the API as dependency to your Integration Namespace.

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 between microservices that also have been developed with IBM Industry Solutions 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.

Example of a binding:

{
  "url": "https://example.com",
  "k5_propagate_security_token": true
}

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 service project 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_security_token - If set to true, the JSON Web Token (JWT) used in your service project 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 IBM Industry Solutions 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'];

...