Staging a draft Product

Stage a draft 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 or API Designer user interfaces (UI). For more information, see Creating and configuring Catalogs.
Note: All references in this topic to a Catalog can also be applied to 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 Product > Stage permission for the target Catalog or Space. For information on configuring Product management permissions for a Catalog or Space, see Creating and configuring Catalogs or Managing user access in a Space.

About this task

You can complete this task either by using either the API Designer UI application, or by using the browser based API Manager UI.

Staging is not available when working offline in API Designer.

A Catalog is a staging target, and behaves as a logical partition of the DataPower® Gateway, and the Developer Portal.

You stage a Product so that the appropriate approvals, internally within the organization, can be given for it to then be published. 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. For information on publishing a Product, see Publishing a Product.

You cannot re-stage an existing Product version to a production Catalog. If you update an API, you must create a new version of that API. Then, create a new version of the Product so that it includes the newer version of the API. For more information on creating new versions of APIs and Products, see Creating a new version of an API definition and Creating a new version of your Product. If Spaces are enabled in a production Catalog, you cannot re-stage the same API or Product version to any Space in the Catalog.

You can, however, re-stage a Product version to the Sandbox Catalog, or other non-production Catalog, for ease of iterative testing. Note that when you re-stage a Product version to a non-production Catalog, any application subscriptions are deleted; this is done to facilitate scripted deployment in a continuous integration environment, where the re-creation of application subscriptions will be controlled by the scripts. If Spaces are enabled in a non-production Catalog and you re-stage a Product version to a different Space to the one in which it was previously staged, it is removed from the previous Space and staged to the newly specified Space.

Validation of the API OpenAPI definition file occurs during the staging or publishing process. The following validation occurs:
  • Validation against the OpenAPI 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 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 API Connect Gateway, then a host must be provided
Note: If the OpenAPI file that defines your API uses a $ref field to reference a fragment of OpenAPI 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 or published (the $ref field is supported only if you are using the API Connect for IBM Cloud developer toolkit). For more information, see Using $ref to reuse code fragments in your OpenAPI files.

Procedure

To stage a Product, complete the following steps:

  1. In the navigation pane, click Develop icon in the navigation pane Develop.
    The Develop: APIs and Products tab opens.
  2. Optional: If you have accounts on multiple provider organizations, you can select a new provider organization for staging and publishing from the Organization menu.
  3. Alongside the Product version that you want to work with, click the options icon options icon and then click Stage.
    If you have more than one version of the Product, ensure that you select the correct one.
  4. Select the Catalog to which you want to stage the Product.
  5. If Spaces have been enabled in the selected Catalog, select the Space that you require.
    Note: The Catalogs that you can select from are those that are defined for the management server and provider organization that you are connected to.

    If you are using the API Manager user interface, the connection details are determined by the API Manager URL that you open, and the user ID with which you log in. If you are using the API Designer user interface, you provide the management server details and user ID in the login window that opens when you first launch API Designer; see Logging into API Connect Designer.

    For details of how to create a Catalog in a provider organization, see Creating and configuring Catalogs.

  6. If, when the staged Product is subsequently published, you want it to be published only to selected gateway services, select Publish to specific gateway services, then select the required gateway services. Only the gateway services whose type matches the gateway type setting for the Product are listed. For information on gateway types, see API Connect gateway types.
  7. Click Stage.

Results

Your Product is staged to a Catalog. You can view the state of the Product in the Catalog in API Manager. If you staged the product from API Designer, ensure you are logged into API Manager with the same user name and password that you used for API Designer. Click Manage icon in the API Manager UI navigation pane Manage in the API Manager UI, then select 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.

What to do next

  • Publish your Product for application developers to access it in the Developer Portal. For more information, see Publishing a Product.