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.
Procedure
To stage a Product, complete the following steps:
-
Select the Products tab in API Designer.
The Products tab opens.
-
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.
-
Click the Publish icon: .
-
Complete either of the following steps:
- If the Catalog to which you want to stage the Product is shown in the list:
- 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.
- 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.
- 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.
- Select the organization and Catalog to which you want to stage the Product to, and click
Next.
- Optional. If you have a LoopBack
application that you want to publish, select the App to publish to.
- Click Save.
- Now you have added the target Catalog, click the Publish icon again, and select the Catalog.
- Select Stage only, followed by Select specific
products and select the Product that you want to stage. Click
Publish.
Your Product is staged.
-
Click Add and Manage Targets and then proceed as follows:
-
Select Add IBM Cloud target or Add a different
target.
-
If required, enter the connection details for the target management server, and click
Sign in.
-
Select the organization and Catalog to which you want to stage the Product.
-
If Spaces have been enabled, select the
Catalog and Space that you
require.
-
Click Save.
- Optional:
If you have a LoopBack application
that you want to publish, select the App to publish to.
-
Click Save.
-
Now you have added the target Catalog, click the Publish icon again, and select the Catalog.
-
Select Stage only, followed by Select specific
products and select the Product that you want to stage. Click
Publish.
Your Product is staged.
-
If Spaces have been enabled, select the
Catalog and Space that you
require.
Your Product is staged to the
Space that you
selected.
Results
Your Product is staged to a Catalog. To view the state of the Product in the Catalog,
open the API Manager UI, select the
Dashboard section in the navigation pane, and click on the required Catalog.
The Product is shown with a state of Staged.
For information about the
lifecycle of a product, see The Product lifecycle.If approval is required to stage Products in the
Catalog, an approval request is sent, and the Product moves to the Pending state; the Product is
staged when the request is approved. If approval is not required, the Product is staged immediately.
For information on configuring Product lifecycle approvals for a Catalog, see Creating and configuring
Catalogs. For information on approving requests, see Approving Product
lifecycle and subscription requests.
Note: If the Product
contains an API that includes a
user-defined policy that has not been imported into
this Catalog, the staging will fail. The
user-defined policy must be available in the
required Catalog for the Product to be staged successfully.
For detailed
instructions on how to import a user-defined policy into a Catalog, see Importing a user-defined policy into a Catalog.