Staging a Product

Stage a Product to a Catalog to create a specific version of that Product, before publishing. When a Product is in the staged state, it is not yet visible to, or subscribable by, any developers. The syndication feature in IBM® API Connect means that if Spaces are enabled for a Catalog, Products can be staged only to a Space within that Catalog.

Before you begin

Ensure that you have a Catalog to stage to in the API Manager user interface (UI). For more information, see Creating and configuring Catalogs.

Note: All references in this topic to a Catalog can also be applied to a Spaces in a Catalog, unless specified otherwise. For more information about Spaces, see Using syndication in IBM API Connect®.

To complete the Product management tasks that are described in this topic, you must either be the owner of the API provider organization, or be assigned Stage permission for the target Catalog. For information on configuring Product management permissions for a Catalog, see Creating and configuring Catalogs.

Note: The API Manager UI also includes the ability to stage Products. However, the preferred method for this task is by using the API Designer UI, as described here. Any steps that are specific to a particular UI are marked with an icon.

About this task

Before a Product can be published, you must first stage that Product to a Catalog. A Catalog is a staging target, and behaves as a logical partition of the DataPower® Gateway or Micro Gateway, and the Developer Portal.

If you stage a Product to a Catalog, editing and then restaging that Product through the Products tab of API Designer or API Manager will effect changes to the staged version.

Note: If you want to publish a LoopBack® project, you must publish both the APIs (by publishing the Products that contain the APIs) and the associated applications so the project can be run. For more information about publishing LoopBack applications, see Publishing a LoopBack application through the API Designer. You can also publish LoopBack applications at the same time as staging your Product by using the following instructions.

If an API has an OpenAPI (Swagger 2.0) definition file, and is part of a Product that is being staged to a Catalog, validation of the OpenAPI (Swagger 2.0) definition file occurs during the staging process. The following validation occurs:

• Validation against the OpenAPI (Swagger 2.0) specification schema
• Validation against IBM extension properties
• Semantic validation, which includes the following types of validation:
  • Ensuring that if an API is enforced by an IBM API Connect Gateway, then the scheme must be HTTPS, or the parameter name for an API key security scheme in the header must be either X-IBM-Client-Id or X-IBM-Client-Secret.
  • Ensuring that if the API is not enforced by an IBM API Connect Gateway, then a host must be provided

Note: If the OpenAPI (Swagger 2.0) file that defines your API uses a $ref field to reference a fragment of OpenAPI (Swagger 2.0) code that is defined in a separate file, the $ref field is replaced with the contents of the target file before the product that contains the API is staged. For more information, see Using $ref to reuse code fragments in your OpenAPI (Swagger 2.0) files.

To stage a Product, complete the following steps:

1. Select the Products tab in API Designer.
   The Products tab opens.
2. Click the Product that you want to work with.
   If you have more than one version of the Product, ensure that you click the version that you want to work with.
3. Click the Publish icon: .
4. Complete either of the following steps:
   • If the Catalog to which you want to stage the Product is shown in the list:
     1. Select the Catalog that you require, and then select Stage only, followed by Select specific products and select the Product that you want to stage. Click Publish. Your Product is staged.
     2. Select the Catalog that you require. Your Product is staged.
   • If the Catalog to which you want to stage the Product is not shown in the list, select Add and Manage Targets.
     1. Select Add IBM Cloud target or Add a different target, enter the connection details for the target management server that you require, and click Sign in.
     2. Select the organization and Catalog to which you want to stage the Product to, and click Next.
     3. Optional. If you have a LoopBack application that you want to publish, select the App to publish to.
     4. Click Save.
     5. Now you have added the target Catalog, click the Publish icon again, and select the Catalog.
     6. Select Stage only, followed by Select specific products and select the Product that you want to stage. Click Publish.
   Your Product is staged.
5. Click Add and Manage Targets and then proceed as follows:
   1. Select Add IBM Cloud target or Add a different target.
   2. If required, enter the connection details for the target management server, and click Sign in.
   3. Select the organization and Catalog to which you want to stage the Product.
   4. If Spaces have been enabled, select the Catalog and Space that you require.
   5. Click Save.
   6. Optional: If you have a LoopBack application that you want to publish, select the App to publish to.
   7. Click Save.
   8. Now you have added the target Catalog, click the Publish icon again, and select the Catalog.
   9. Select Stage only, followed by Select specific products and select the Product that you want to stage. Click Publish.
   Your Product is staged.
6. If Spaces have been enabled, select the Catalog and Space that you require.
   Your Product is staged to the Space that you selected.