Tutorial: Connect an API Product with an Integration runtime

Using the assembly canvas, you can create an API Connect workflow with Kubernetes resources. You can use the RESTful API to create and expose service data (for example, ‘Get customer address’ from a CRM system) or functionality (for example ‘Place customer Order’ into an Ordering database) of a service, ensuring that other applications can easily access the data through an API. This tutorial focuses on two instance types: API Products and Integration runtimes.

Before you begin

Confirm the following prerequisites before you begin the tutorial:

IBM Cloud Pak® for Integration 16.1.1 or later is installed, including deployment of a Platform UI instance. For more information, see Installing.
Within the Cloud Pak for Integration installation, deploy the following operators with their corresponding instances:
- IBM App Connect operator.
- IBM API Connect operator. Deploy an API Connect cluster instance.
For more information about installing operators, see Installing the operators. For more information about deploying instances, see Deploying an instance by using the Platform UI or Deploying an instance by using the CLI.

Overview

In this procedure, a node refers to any instance or resource that you create in the canvas. For any configuration fields that are not called out in these steps, keep the default values.

1. Start a new assembly canvas

Building your flow in an assembly allows you to easily manage all the components and take advantage of default settings that save you time and effort. The canvas provides an intuitive graphical interface for building your assembly.

Tip: If you need to leave your assembly for a period of time while you are working on it, it is not saved automatically. To save your configuration, click the "Save as draft" icon at the top of the screen. Your assembly appears in the list on the home page. When you are ready to continue, click the Options menu icon at the end of the row for your assembly, then select Edit

Log in to the Platform UI. On the Platform UI home page, click the Build with assembly canvas tab.
In the "Build with assembly canvas" dialog, enter the name for your canvas, demo-integration. Click Build.

2. Create a Configuration resource

This configuration holds the access credential values that the Integration runtime uses to access the GitHub repo that contains the BAR file.

A BAR file packages all the components that are required for deploying an integration solution to an IBM integration server. BAR files are deployed to integration nodes or servers to run the integration logic. They help manage versions of integration solutions and ensure consistent deployment across environments.)

Click to open the Resources dropdown.
Drag and drop a Configuration resource onto the canvas.
Double-click the node to open the configuration panel.
Enter the following values, which are the credentials used by the Integration runtime for accessing the BAR file:
- Metadata section
  - Name - The name of this configuration, barauth-demo
- Data - Enter the GitHub base64-encoded credentials:
```
eyJhdXRoVHlwZSI6IkJBU0lDX0FVVEgiLCJjcmVkZW50aWFscyI6eyJ1c2VybmFtZSI6IiIsInBhc3N3b3JkIjoiIn19Cg== 
```
  Tip: The string above resolves to empty (placeholder) credentials: {"authType":"BASIC_AUTH","credentials":{"username":"","password":""}} This configuration is for a demo that is accessing a public repository. In a production environment, you will need to specify the values.
- Description - Authentication for public GitHub, no credentials needed
  - Type - Select barauth.
Click Update.

3. Create an Integration runtime

The Integration runtime helps the BAR file do its work. The BAR file, when added to the integration runtime, puts a message on a queue.

Click to open the Independent instances dropdown.
Drag and drop an Integration runtime instance onto the canvas.
Double-click the node to open the configuration panel. The UI form tab should be highlighted.
Enter the following values:
- Details section
  - Name - The name of this node, integration-runtime-demo.
- License section
  - Accept - To accept the license, select the checkbox.
  - Use - Select CloudPakForIntegrationProduction`.
- Bar URLs - Click Add to open the fields, if needed.
  - Bar URL - The URL for accessing the BAR file; enter https://github.com/demo-test-source/demo-source/raw/refs/heads/main/api-demo/api-demo.bar.
- Configurations - Click Add to open the fields, if needed. Configuration - The name of the configuration that this node is connecting to so it can access GitHub credentials; enter barauth-demo.
Click Update.

4. Configure API Connect

Create the following API Connect resources:

An organization called main-demo in API Connect Cloud Manager.
Inside the organization, a catalog called main-demo-catalog
A consumer org owner called main-demo-corg-admin
A consumer org, called main-demo-corp
A portal for the catalog, called main-demo-catalog
A secret called apim-credentials in the namespace where API Connect is installed. For more information, see "Create a secret with your API Manager credentials" in Using the API Product Kubernetes resource.

Tip: If you do not want to create the API Connect resources manually, you can run this demo script.

5. Create an API Product instance

An API Product instance declaratively defines and manages API Products in an API Manager by using YAML Kubernetes objects. For more information about API products, see Using the API and API Product Kubernetes resources.

From the Independent instances section in the navigation panel, drag and drop an API Product instance onto the canvas.
Double-click the node to open the configuration panel.
Enter the following values:
- Metadata section
  - Name - The name of this node; enter demo-api-product,
- Share section
  - API Manager
    - Credentials secret - apim-credentials
    - Provider organization - main-demo
  - Catalog - main-demo-catalog
- State - Select Published.
- Definition section
  - Info
    - title - `api-product1
    - name - api-product (do we need optional value?)
    - description - testing (do we need optional value?)
    - summary - testing (do we need optional value?)
- APIs
  - Integration runtimes - Click Add to open the fields, if needed.
    - Name - integration-runtime-demo
Click Update.

6. Deploy and test the assembly

The completed assembly should be similar to the screenshot:

Complete assembly with API and Integration runtime

Click Create.

The assembly begins building and deploying the nodes. Your new assembly demo-integration appears in the list of deployed instances on the Platform UI home page.

When the status changes to Ready, click the dropdown arrow to expand the list of all components in your assembly and confirm that they are ready (successful) as well.

Implementation details

By using an assembly in Cloud Pak for Integration, you can build and deploy the entire API plus management stack in one place. This process automates:

Creating a new integration runtime instance and deploying an API to it.
From the API in the Integration runtime, extracting the API specification and deploying it to API Connect.
Using the declarative API product to publish the API in an API Connect cluster.
Publishing the API to the API Connect Portal to enable discoverability and self service, and using the API Connect Gateway for security and rate-limiting.
Integrating the API in the API Connect Gateway with the API Implementation in the App Connect cluster.

A RESTful API defined by an OpenAPI Specification defines your API. The definition includes these elements:

Required input parameters (for example, customerNumber)
Returned data (for example, customerName, addressLine1 and addressLine2)
The operations that are available (Get Customer, Create Customer, and so on)

App Connect creates the API specification and implements your API. The API implementation in this assembly enables the following capabilities:

Secure access, to ensure only credentialed users can access the API
Publishing and sharing, to make the API discoverable
Rate limiting, to control usage in order to prevent overload
Lifecycle management, to stage, publish, deprecate, and retire APIs = Self-service signup, to automate credential creation for users
Analytics, to track usage, performance, and consumer behavior