The product lifecycle

When you manage your product versions, you move them through a series of lifecycle states. From initially staging a Product version to a Catalog, through to publishing to make the Product version available to your application developers, and to eventual retiring and archiving. The syndication feature in IBM® API Connect means that Product lifecycle states can also be managed within Spaces in the associated Catalog.

Product lifecycle state diagram

The following diagram shows the possible lifecycle states for a Product version, and the Product management operations that move a Product version from one lifecycle state to another. For example, the retired operation moves a Product version from the Published to the retired state.

Note: The same Product lifecycle states apply irrespective of whether your Product is managed within a Catalog, or within a Space in a Catalog. For more information about the syndication feature, see Using syndication in API Connect.

If approval is required for a Product management operation, an approval request is sent and the Product version moves to the pending state. When the request is approved, the operation is completed and the Product version moves to the next lifecycle state. If approval is not required, the operation is completed immediately.

Note: Approval is not required for the following lifecycle state transitions:

Retired to staged.
Deprecated to published.

For more information about configuring Product lifecycle approvals for a Catalog, see Creating and configuring catalogs. For more information about 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.
Product lifecycle approvals can be configured only at the Catalog level. This feature is not available at the Space level.
To view the subscription tasks history, complete the following steps:
- In the navigation pane of the API Manager UI, click Manage, then select the catalog that you want to work with.
- Click Tasks tab.
- Click Approvals history from the navigation pane.
You can view the history of Product lifecycle requests and approvals, by clicking the options icon alongside the Product that you want to work with, and selecting View Approval History.

The following sections describe the various lifecycle states for a Product version.

Note: All references in this topic to a Catalog can also be applied to a Space in a Catalog, unless specified otherwise.

Draft

The draft state for a Product or API is when a Product or API definition is not deployed and is not associated with any Catalog.

Staged

When you stage a Product, a copy of the Product version is deployed to the target Catalog. Staged is the initial state when you publish a Product. When a Product is in the staged state, it is not yet visible to, or subscribable by, any developers. For more information about staging a Product, see Staging a Product.

You stage a Product so that the appropriate approvals, internally within the organization, can be given for it and the product can be published. For more information about configuring Product lifecycle approvals for a Catalog, see Creating and configuring Catalogs. For more information about approving requests, see Approving Product lifecycle and subscription requests. For more information about publishing a Product, see Publishing a Product.

Published

When you publish a Product, a fixed copy of the Product version is deployed to the target Catalog. The Product version is visible to, and subscribable by, the targeted developers or communities. When a Product is published in a Catalog, the visibility and subscription settings can be changed for the published version of that Product. Any further changes require a new version of the Product to be staged and published before they take effect.

If you replace a Published Product with a Staged or Deprecated Product, the replacement Product is published, and the replaced Product is retired.

If you supersede a Published Product with a Staged or Deprecated Product, the superseding Product is published, and the superseded Product is deprecated.

For more information about publishing a Product, see Publishing a Product.

Note: If you want to update a Product, you must republish it. The products:update command only updates a Product's metadata.

Deprecated

When you deprecate a Product, the Product version is visible only to developers whose applications 're subscribed. No new subscriptions to the plans in the Product are possible. For more information about deprecating products, see Deprecating a Product.

A Product is also deprecated if you supersede it with another Product. For more information, see Superseding a Product with another Product.

Retired

When you retire a Product, the Product version cannot be viewed and cannot its plans be subscribed to, and all of the associated APIs are taken offline. For more information about retiring products, see Retiring a Product.

A Product is also retired if you replace it with another Product. For more information, see Replacing a Product with another Product.

Replace product

Use the replace product option when you want to replace product A with product B and migrate all subscriptions. This action retires the source product and publishes the destination product. For more information, see Replacing a Product with another Product.

Migrate Subscriptions

Use Migrate Subscriptions to perform the same function as Replace Product, except it does not retire the source product, and the destination product must already be published.

You can also use Migrate Subscriptions to migrate individual subscriptions between different products or between plans within the same product. For more information, see Migrating application subscriptions to another Product and Migrating application subscribers to new Product versions.

Supersede product

Use Supersede Product to replace product A with product B and migrate all subscriptions at a later time. This option deprecates the source product and publishes the destination product.

When a product is deprecated, new subscriptions are not allowed, but existing subscriptions continue to function until they are migrated. Consumers can migrate all subscriptions or individual subscriptions at a time that suits them. For more information, see Superseding a Product with another Product.

Set migration target

Use Set Migration Target option to perform the same function as the Supersede option. It prepares subscriptions for migration to the destination product but does not deprecate the source product. The destination product must already be published. For more information, see Migrating application subscribers to new Product versions.

Note:

Both Supersede Product and Set Migration Target assume that the source product will no longer be used after all subscriptions are migrated and that it will not be used as a migration target in the future.

These options are typically used when a new version of product A supersedes an older version of the same product. The source and destination products are labeled with the attributes superseded_by and supersedes, respectively.

Execute Migration Target

Use Execute Migration Target to force the migration of all subscriptions from a superseded product before retiring it. For more information, see Migrating application subscribers to new Product versions.

Note:

Supersede Product and Set Migration Target prevent setting the migration target to an older product version to avoid circular dependencies, where two products point to each other as migration targets.

To reset the migration target to an older version, first clear the superseded_by and supersedes settings created by Supersede Product or Set Migration Target. Then, run Execute Migration Target to migrate all subscriptions to the destination product.

After all subscriptions are migrated, retire the source product. To reuse it, restage and republish it before using Set Migration Target with the older version.