Managing API Products

Use the apic products and apic apis commands to manage Products and APIs that have been published to IBM® API Connect Catalogs. Use the --scope space option to manage Products and APIs that have been published to Spaces within Catalogs.

Product management command summary

The following table summarizes the commands available for managing API Products. Usage examples follow.
Example command Description
apic config:set catalog=https://platform-api.myserver.com/api/catalogs/myorg/sandbox Set the default Catalog.
apic login --username some-user --password some-password --server platform-api.myserver.com --realm provider/my-identity-provider Login into the management server.

For full details on how to log in to your management server from the CLI, see Logging in to the management server.
apic create:api --title Routes --product "ClimbOn" Create the Product and API.
apic products:publish climbon.yaml Publish the Product to the default catalog. Add --stage argument to stage the Product.
apic products:list-all --scope catalog List the Products in the default catalog.
apic products:get climbon:1.0.0 --output - Display the Product's properties. Omit the output argument to download to a file.
apic apis:list-all --scope catalog List the APIs in the Catalog.
apic apis:get routes:1.0.0 --output - Get the API properties. Omit the output argument to download to a file.
apic products:replace climbon:1.0.0 mapfile.txt Replace the Product indicated on the command line with the staged or published Product designated in the mapfile. This retires the replaced Product.
apic products:supersede climbon:1.0.0 mapfile.txt Supersede the Product indicated on the command line with the staged or published Product designated in the mapfile. This deprecates the superseded Product.
apic products:delete climbon:1.0.0 Delete the Product from the Catalog. The Product must be either retired or deprecated.

Using the products and apis commands through a full lifecycle

This example shows a complex lifecycle where a new version of a Product and API replaces the original version at run time.

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 with the apic publish command. For more information, see Using $ref to reuse code fragments in your OpenAPI files.
Set the default Catalog and login to the mgmnthost.com API Connect cloud
apic config:set catalog=https://platform-api.myserver.com/api/catalogs/climbon/sandbox
apic login --username some-user --password some-password --server platform-api.myserver.com --realm my-identity-provider

For full details on how to log in to your management server from the CLI, see Logging in to the management server.

Create and publish an initial version
apic create:api --title Routes --version 1.0.0 --filename routes100.yaml
apic create:product --title "Climb On" --version 1.0.0 --apis routes100.yaml --filename climbon100.yaml
apic products:publish climbon100.yaml
Create a new version to fix a bug in the API, stage it to the Catalog
apic create:api --title Routes --version 1.0.1 --filename routes101.yaml
apic create:product --title "Climb On" --version 1.0.1 --apis routes101.yaml --filename climbon101.yaml
apic products:publish --stage climbon101.yaml
Inspect the Catalog
apic products:list-all --scope catalog
This produces a list of all Products in the catalog. Copy the ID of the climbon:1.0.1 Product. The ID resembles the following example.

https:/server/api/catalogs/3eca6046-3c27-4ad/ab8772bf-0f65-45/products/8f854623-bda1-4f9
Create a mapping file
For example, if you are replacing a Product, the mapping file specifies the Product that you want to replace, and the mapping of the Plans from the source Product to the target Product. For example, if you are replacing climbon:1.0.0 with climbon:1.0.1 then product_url property specifies the URL of climbon:1.0.0.
This file takes the following form: 

product_url: https:/server/api/catalogs/{id}/products/{id}
plans:
- source: {source_plan_name_1}
  target: {target_plan_name_1}
- source: {source_plan_name_2}
  target: {target_plan_name_2}
            .
            .
            .
Note:
  • The source and target Plan names can be the same or different.
  • Every Plan in the Product you are replacing must be mapped to a Plan in the replacement Product.
"Hot-replace" version 1.0.0 with 1.0.1
apic products:replace climbon:1.0.1 PRODUCT_PLAN_MAPPING_FILE
After it is replaced in this way, a Product is retired. It is no longer active.
Note: The Product specified on the command line is the replacement Product. For example, if you are replacing climbon:1.0.0 with climbon:1.0.1 then the Product specified on the command line is climbon:1.0.1.
Supersede version 1.0.0 with 1.0.1
Rather than hot-replacing an existing Product with a new one (usually an updated version), you can supersede the existing Product with a new one. When you replace a Product, all external application subscriptions to that Product are automatically moved to the new Product. When you supersede a Product, the subscriptions are not automatically moved to the new Product, some action must be taken to subscribe external applications to the superseding Product.
The command to supersede a Product uses the same mapping file as the command to replace a Product. The name of the superseding Product is given on the command line.
apic products:supersede climbon:1.0.1 PRODUCT_PLAN_MAPPING_FILE
Once superseded, a Product is marked deprecated, meaning that no further subscriptions to the Product are allowed, although it is still active and existing subscriptions still work.
Note: The Product specified on the command line is the superseding Product. For example, if you are replacing climbon:1.0.0 with climbon:1.0.1 then the Product specified on the command line is climbon:1.0.1. The mapping file specifies the URL of the Product you are superseding.
Set a migration target
It is possible to set a migration target for the existing Product. This helps migration.
Use a command like the following to set the migration target. 
apic products:set-migration-target climbon:1.0.0 PRODUCT_PLAN_MAPPING_FILE
Note: The Product specified on the command line is the Product from which you want to migrate subscriptions. The mapping file specifies the target Product for the subscriptions.
Once a migration target is set, external application developers will be able to migrate their application subscriptions through the Developer Portal with ease. It is also possible to execute a subscription migration using the following command. 
apic products:execute-migration-target climbon:1.0.0
Delete a Product
When the replaced or superseded Product is no longer needed, it can be deleted. 
apic products:delete climbon:1.0.0

Additional Product and API operations

In addition to the lifecycle management capabilities, you can download Products and APIs in a catalog or space using the clone sub-command:
Command Description
apic products:clone Download all Products and their APIs from the catalog or space.
apic apis:clone Download all APIs from the catalog or space.
It can also be useful to clear all Products and their APIs from a Catalog, particularly for a development Catalog (you must provide the name of the Catalog as the value of the --confirm parameter):
apic products:clear --confirm catalog_name
where catalog_name is the name of the Catalog.

You can use a Space to partition a Catalog so multiple teams can manage Products and APIs independently in a single Catalog. A Space is conceptually like a subcatalog, except that Products and APIs in all Spaces in a given Catalog are published to the same developer portal. For more information about Spaces, see Using syndication in IBM API Connect.

To manage the Products and APIs that have been published to a Space, include the --scope space option with the apic products and apic apis commands. For example, to list the Products that are contained in a Space called flights, use the following command:
apic products --scope space --space flights --catalog production --org climbonorg --server platform-api.myserver.com

Changing the lifecycle state of a Product in a Catalog or Space

To directly change the lifecycle state of a Product that has previously been staged or published to a Catalog or Space, complete the following steps:

  • Enter the following command (the terminating hyphen character means that the command takes input from the command line):
    apic products:update product_name:version --server mgmt_endpoint_url --org organization --scope scope --catalog catalog [--space space] -
    where:
    • product_name is the name of the Product whose lifecycle state you want to change.
    • version is the version of that Product.
    • mgmt_endpoint_url is the platform API endpoint URL.
    • organization is the name of the provider organization in which the Product was previously staged or published.
    • scope has one of the following values:
      • catalog if the Catalog does not have Spaces enabled.
      • space if the Catalog has Spaces enabled. If you specify space for the --scope parameter you must also supply the --space parameter.
    • catalog is the name of the Catalog in which the Product was previously staged or published.
    • (optional) space is the name of the Space. The --space parameter is required if the Catalog has Spaces enabled, in which case you must also include --scope space in the command.
    The command returns:
    Reading PRODUCT_FILE arg from stdin
  • Enter the following data, followed by a new line:
    state: new_state
    where new_state is the state that you want to change the Product to, and must have one of the following values.
    • staged
    • published
    • deprecated
    • retired
    • archived
  • Press CTRL D to terminate the input. If the command is successful, the lifecycle state change is confirmed.
    For example:
    apic products:update finance:1.0.0 --server https://myserver.com --org development --scope catalog --catalog sandbox -                    
Reading PRODUCT_FILE arg from stdin
state: published
finance:1.0.0    [state: published]   https://myserver.com/api/catalogs/dce12994-a6a1-487b-83b6-c73bd8498799/006827d5-9e82-427a-abe6-be5b126210f7/products/0f0af980-f505-4f36-b09c-d7b1c9c1a2f2
Note:

The command will not succeed if the lifecycle state change you are attempting is not permitted.

For example, the following lifecycle state changes are permitted:
  • staged to published
  • deprecated to retired
The following lifecycle state changes are not permitted:
  • published to staged
  • retired to published

For full details, see The Product lifecycle.

To list all Products in a Catalog or Space, together with their lifecycle states, use the following command:
apic products:list-all --server mgmt_endpoint_url --org organization --scope scope --catalog catalog [--space space]
For example:
apic products:list-all --server https://myserver.com --org development --scope catalog --catalog sandbox
graphql-services:1.0.0    [state: staged]      https://myserver.com/api/catalogs/dce12994-a6a1-487b-83b6-c73bd8498799/006827d5-9e82-427a-abe6-be5b126210f7/products/7652d568-b396-4bfa-bf71-2f18cea63737   
finance:1.0.0             [state: published]   https://myserver.com/api/catalogs/dce12994-a6a1-487b-83b6-c73bd8498799/006827d5-9e82-427a-abe6-be5b126210f7/products/0f0af980-f505-4f36-b09c-d7b1c9c1a2f2
To find out the lifecycle state of a specific Product, use the following command:
apic products:get product_name:version --server mgmt_endpoint_url --org organization --scope scope --catalog catalog [--space space] --fields state --output -
For example:
apic products:get finance:1.0.0 --server https://myserver.com --org development --scope catalog --catalog sandbox --fields state --output -
state: published

Example scripts

A set of example toolkit scripts that demonstrate how to create and manage organizations, users, apps, Products and APIs are available at https://github.com/ibm-apiconnect/example-toolkit-scripts.