Publishing APIs and applications

To publish APIs and applications by using the developer toolkit of IBM® API Connect, you set configuration variables to define where you want to publish, log in to the target cloud platform, and then use the appropriate publishing commands.

See the following sections for more information:

Setting configuration variables

The apic config command provides global and project-based configuration variables that specify the target Catalog for publishing APIs and applications. The values of these variables are stored in ~/.apiconnect/config (for global variables) and project-dir/.apiconnect (for project variables). For a full list of configuration variables, see Overview of the command-line tool.

Set the catalog configuration variable to the URI of an API Connect Catalog to define a default Catalog target for all commands managing Catalogs. The catalog URI has the form:

https://mgmt_endpoint_url/api/catalogs/org_name/catalog_name

where mgmt_endpoint_url is the platform API endpoint URL, org_name is the provider organization name, and catalog_name is the Catalog name. The mgmt_endpoint_url portion sets the default value of the --server option, the org_name portion sets the default value of the --org option, and the catalog_name portion sets the default value of the --catalog option; you can override any of these values by including the corresponding option in a command.

Set the space configuration variable to the URI of an API Connect Space, to define a default Space target for all commands that manage Spaces. The space URI has the form:
https://mgmt_endpoint_url/api/spaces/org_name/catalog_name/space_name
where mgmt_endpoint_url is the platform API endpoint URL, org_name is the provider organization name, catalog_name is the Catalog name, and space_name is the name of the Space. The mgmt_endpoint_url portion sets the default value of the --server option, the org_name portion sets the default value of the --org option, the catalog_name portion sets the default value of the --catalog option, and the space_name sets the default value of the --space option; you can override any of these values by including the corresponding option in a command.

Although setting these configuration variables is not required, doing so simplifies commands that interact with API Connect clouds by providing default values for frequently used command-line options.

Here is an example of publishing with and without the catalog configuration variable set.

Without the configuration variable set:

apic products publish climb-on.yaml --server mgmnthost.com --org climbon --catalog sandbox

With the configuration variable set:

apic config:set catalog=https://platform-api.myserver.com/api/catalogs/climbon/sandbox
catalog: https://platform-api.myserver.com/api/catalogs/climbon/sandbox
apic products publish climb-on.yaml

You can override default values provided by the catalog configuration variable by providing one of the standard options with a different value. For example, use the --catalog option with the apic products publish command to specify the qa Catalog:

 apic products publish climb-on.yaml --catalog qa

Don't forget about global configuration variables. If you use the same Catalog as the default target for multiple projects, set the value globally:

 apic config:set --global catalog=https://platform-api.myserver.com/api/catalogs/climbon/sandbox
Note:

If you have an environment variable of the same name as a CLI configuration property then, by default, its value will override the value of the corresponding CLI configuration property for any CLI command at that scope.

For example, if you have defined an environment variable called SPACE then, by default, that value will be assumed for the value of the --space parameter in the following command, regardless of any space configuration property setting:
apic products:publish my_product.yaml --scope space

To prevent environment variables overriding CLI configuration properties, define an environment variable called APIC_LOAD_FROM_ENV, set to the value false.

Logging in to API Connect

Use the apic login and apic logout commands to manage your authentication. For details, see rapic_cli_login.html.

Publishing APIs

Publishing APIs to API Catalogs in API Connect clouds enables you to socialize the APIs by using the developer portal and secure them by using the Gateway.

An API Product (or simply Product) is used to compose APIs for publishing. API Product managers can use it to bundle one or more APIs together, control the visibility of the Product in the developer portal (for example, only allow partners x, y, and z to view and subscribe to the Product), and define Plans to provide consumption options. The Products that reference the APIs and define the consumption Plans are also the primary unit of lifecycle management for APIs.

Use the apic products publish command (equivalent to apic products:publish) to publish API Products to an API Connect cloud. The following example demonstrates how to create APIs composed by a Product, and publishing the Product and its APIs to a Catalog:

apic create:api --title Routes
apic create:api --title Ascents
apic create:product --title "Climb On" --apis "routes.yaml ascents.yaml"
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 provider/default-idp-2
apic products publish climb-on.yaml

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

Add the --stage option to apic publish to stage the Product into a Catalog instead of publishing it. Products in a Catalog can be in the following states: staged, published, deprecated, or retired. For example:

apic products publish --stage climb-on.yaml

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.

If default configuration values have been set for the Space, Catalog, organization and management server, the following publish command could be used:
apic products publish --scope space product.yaml
where product is the name of the product that you want to publish.
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.