Superseding a Product with another Product

You can supersede a published Product with another Product by using the API Manager.

Before you begin

The superseding Product must be in the Staged, Deprecated, or Published state. The Product to be superseded must be in the Published state.

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 Manage permission for Products in the Catalog that contains the Product. If you have View permission for Products, you have read-only access to the Product management page. For information on configuring Product management permissions for a Catalog, see Creating and configuring Catalogs.

The syndication feature in IBM® API Connect means that Products can be contained within a Space in a Catalog. In this case, 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 Manage permission for Products in the Space that contains the Product. For information on configuring Product management permissions for a Space, see Managing user access in a Space.

[V5.0.5 or later]Restriction: If the Products are contained within a Space in the Catalog, and the superseding action is being made at the Space level, the superseding Product must be located in the same Space as the Product to be superseded. If the supersede action is being made at the Catalog level, Products can be superseded across Spaces. For more information about the Space feature, see Using syndication in IBM API Connect.

About this task

When you supersede a Product with another Product, the following actions are taken:
  • The superseding Product is published.
  • The same visibility, subscriber, and gateway enforcement settings from the original Product are used for the superseding Product.
  • The original Product is moved to the Deprecated state. When a Product is deprecated, application developers that are already subscribed to the Product can continue to use it, but no new developers can subscribe to the Product. A deprecated product can be published again if required.

Although you can publish to a development Catalog, the development Catalog should be used only for testing purposes. Similarly, a Developer Portal created from a development Catalog must be used for testing purposes only, and not for production use. For more information on Catalogs, see Working with Catalogs.

[V5.0.4 only] When you use the test tool in a development Catalog, any Product that you test is forced through and overwrites staged and published Products even if the APIs are being used in the Developer Portal.

Note:
  • When you publish, replace, or supersede a Product, there is a short delay before the APIs in the Product are available to be called through the API Connect gateway.
  • All references in this topic to a Catalog, can also be applied to a Space in a Catalog, unless specified otherwise.

Procedure

To supersede a Product, complete the following steps:

  1. On the Dashboard of the API Manager UI, select the Catalog that you want to work with.
    The Products tab of the Catalog opens, and all of the Products available in that Catalog are displayed. You can select which states are shown by clicking the filter icon in the Search banner and selecting one or more of the State check boxes.
  2. [V5.0.5 or later] If the Product that you want to work with is contained within a Space, select the required Space by clicking the down arrow next to the Catalog name in the submenu navigation banner.
    The Products tab of the Space opens, and all of the Products available in that Space are displayed. You can select which states are shown by using the filter check boxes in the State bar.
  3. Alongside the superseding Product version, click the Manage icon Product manage icon and then click Supersede an existing Product..
    The Supersede an existing product window opens.
  4. Click the Product that you want to supersede and then click Next.
  5. From the drop-down list, select which Plans from your new Product correspond to Plans in your old Product.
    API Manager automatically completes this page when there is a clear correspondence. For example, when there are Plans in both the new and old Products that are called Gold.
  6. Click Supersede.
    If approval is required to supersede Products in this Catalog, an approval request is sent, and the Product moves to the Pending state; the Product is superseded when the request is approved. If approval is not required, the Product is superseded 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:
    • Approval for Product lifecycle state changes in a Catalog is disabled by default. You must explicitly enable the Product lifecycle state changes that you want to enforce.
    • [V5.0.5 or later]Product lifecycle approvals can be configured only at the Catalog level. This feature is not available at the Space level.

Results

Your superseding Product is in the Published state.

The Product that was superceded is in the Deprecated state.

Your superseding Product is published to your preferred organizations or communities. Application developers within the groups you selected can see and use the APIs within the Product. The original Product is deprecated.

Any application developer requests to use your Product are displayed on the Approvals tab in the containing Catalog, where you can decline or accept the request.

[V5.0.8 or later]Customers who are already subscribed to the deprecated Plan are not disconnected from their credit card billing provider subscription to the deprecated Product, as it is still available for existing customers to use. New customers cannot subscribe to the deprecated Plans.