Using the API and API Product Kubernetes resources

By using the API Kubernetes resource and API Product Kubernetes resource together (and with other Kubernetes resources in Cloud Pak for Integration, like integration runtimes), you can control the APIs and API Products in an API Manager.

The power of using Kubernetes resources is that you can declare the desired state of an API and an API Product, instead of using the API Manager UI or APIs to imperatively configure them.

Benefits of declarative configuration

Declarative configuration enables you to do the following:

  • Store the configuration in source control, enabling git workflow patterns such as reviews, approvals, and promotion between environments without needing to use the API Manager UI or API.

  • Avoid configuration drift. Changes to an API or API Product that are made through other means are reverted to the desired state.

  • Have a single version of the source of truth, enabling reliable recreation of environments for disaster recovery.

  • Automate the creation of APIs and Products by using a declarative pipeline such as ArgoCD.

  • Easily re-create the same APIs and Products in a new API Manager by updating the pipeline or credentials with a new API Manager address.

Working with resources in the Platform UI

Developers can also manage and develop an API resource and an API Product resource in the Platform UI. Working in the Platform UI gives you access to additional enablement features for working with Kubernetes resources. These features include:

Associating an API resource with an API Product resource

As described previously, associating an API resource with an API Product resource enables you to define the desired state of all APIs and API Products in an API catalog. The following steps are a high-level overview of the process.

  1. The user authors an API specification by using a tool such as the developer toolkit from API Connect.

  2. The user places the API specification in source control. The specification can include fields that are parameterized. For more information, see "Parameterization" in Using the API Kubernetes resource.

    • If you're not using source control for your API specification, you can store it in a ConfigMap on the cluster. The API resource references this ConfigMap to get the API specification. For more information, see "ConfigMap example" in Using the API Kubernetes resource.

  3. The user creates an API resource. This resource references the URL of the source control location for the API specification (or the ConfigMap on the cluster, if you're not using source control). The API resource can include both parameters, if you're using parameterization, and additional metadata attributes for the API specification.

  4. The user creates an API Product resource. This resource references one or more API resources. The API Product resource allows the user to configure the product definition, which includes fields for the provider organization, state, catalog, plans, and rate limits.

  5. The user configures the API Product to reference a secret, which specifies the API Manager that you associate this API Product with.

    • The API Manager can be any API Manager form factor, such as self-managed or as a service.

    • You can have multiple secrets on the same cluster, each pointing at a different API Manager. Different API Products can then reference different secrets.

  6. When the API Product resource is created, the user adds it to the specified API Catalog.

  7. If the API Portal and API Gateway are configured for this catalog, the user can also set the spec.state of the API Product resource to Published. This configuration adds the API Product to an API Portal that is enforced with an API Gateway.

Any changes to or deletion of associated resources results in a corresponding change to the API Catalog. For example, you can make a lifecycle change by deprecating an API Product (by updating the value of the spec.state to Deprecated in the resource). That API Product is then listed as Deprecated in the API Catalog.

Figure 1. End-to-end flow using the API and API Product resources together
End-to-end flow using the API and API Product resources together

This diagram is an example of the previous end-to-end flow as it could be created in the Platform UI canvas. Note that the orientation of the flow diagram in the canvas is reversed; the first component (the ConfigMap) is on the far right, and the last component (the API Product) is on the far left.

Figure 2. APIs and API Products in the canvas
APIs and API Products in the canvas

Associating an integration runtime with an API Product

For an API implementation that is part of an App Connect integration runtime, you can reference that runtimes from an API Product resource. This reference adds the APIs that are in the runtime BAR files to an API Catalog. The following steps are a high-level overview of the process.

  1. The user creates REST API flows in either an Integration design instance or an App Connect Toolkit. This process creates a BAR file. Because you have already defined the API by using an Integration design instance or an App Connect Toolkit, you do not need to re-create the API specification. You can also use Integration design to author API extensions.

  2. The BAR file is published to a hosting location. The hosting location might be source control, the Integration dashboard, or any other application supported by App Connect.

  3. The Integration runtime is created. The runtime instance references the BAR file location, and (optionally) a Configuration. The URL for the BAR file must contain a commit hash. For example:

    https://github.com/IBM/ibm-integration/raw/77b7c62981f7854739473eca57aa552d61391e2c/bars/my-bar.bar

  4. The user configures the product definition in the API Product resource, including the provider organization, state, catalog, plans, and rate limits.

  5. The user configures the API Product to reference a secret, which specifies the API Manager that you associate this API Product with.

    • The API Manager can be any API Manager form factor, such as self-managed or as a service.

    • There can be multiple secrets on the same cluster, each pointing at a different API Manager. Different API Products can reference different secrets.

  6. When the API Product resource is created, the user adds it to the specified API Catalog.

  7. If the API Portal and API Gateway are configured for this catalog, the user can also set the spec.state of the API Product resource to Published. This configuration adds the API Product to an API Portal that is enforced with an API Gateway.

Configuring an API resource to mediate between the integration runtime and the API Product

Instead of linking an API Product directly to an Integration runtime, you can configure an API resource to reference the runtime, and then configure an API Product resource to reference that API resource. One advantage of this approach is that you can use the API resource to include parameters, if you're using parameterization, or add further metadata attributes for the API specification.

Figure 3. End-to-end flow of using the API and API Product resources with integration runtimes
End-to-end flow of using the API and API Product resources with integration runtimes

Like the previous example, all of these resources can be authored in the Platform UI canvas:

Figure 4. API Products and Integration runtimes in the canvas
API Products and Integration runtimes in the canvas