Publishing APIs and applications

Setting configuration variables

The apic config command provides global and project-based configuration variables that specify the target Catalog and App 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 Using configuration variables.

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:

apic-catalog://management_server/orgs/org_name/catalogs/catalog_name

where management_server is the API Manager server, org_name is the organization name, and catalog_name is the Catalog name. You can override the values set by the Catalog URI configuration variable by using the --catalog command-line option.

Set the app configuration variable to the URI of an API Connect App to define the default App target for all commands managing applications. The app URI has the form:

apic-app://management_server/orgs/org_name/apps/app_name

apic-org://management-server/orgs/org-name

You can append the port number to the server name if it is not the default value of 443.

The easiest way to determine the values for these configuration variables is to sign in to the API Manager of your provisioned API Connect service or your on-premises cloud, and click on the link icon of the Catalog or App to which you want to publish your API or application. The dialog that appears will provide you with the identifier of the Catalog or App along with the appropriate config:set 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:

apic-space://management_server/orgs/org_name/catalogs/catalog_name/spaces/space_name

where management_server is the API Manager server, org_name is the organization name, catalog_name is the Catalog name, and space_name is the name of the Space. You can override the default values set by the Space URI configuration variable by using the --server, --organization, --catalog, and --space command-line options.

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

Without the configuration variable set:

apic publish climb-on.yaml --server mgmnthost.com --organization climbon --catalog sb

With the configuration variable set:

apic config:set catalog=apic-catalog://mgmnthost.com/orgs/climbon/catalogs/sb
apic config:set org=apic-org://mgmnthost.com/orgs/climbon
apic 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 publish command to specify the qa Catalog:

 apic 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=apic-catalog://mgmnthost.com/orgs/climbon/catalogs/sb

Logging in to cloud platforms

Use the apic login and apic logout commands to manage your authentication credentials for IBM® API Connect clouds. Unlike many systems, API Connect enables you to be logged in simultaneously to multiple clouds, so that you can easily publish and manage APIs and applications to disparate on-premises and IBM Cloud targets.

Log in supports both interactive and non-interactive modes. To log in interactively:

$ apic login
Enter your API Connect credentials
? Server: us.apiconnect.ibmcloud.com
? Username: username@example.com
? Password (typing will be hidden) ****************
Logged into us.apiconnect.ibmcloud.com successfully

You can perform scripted non-interactive log in by using the --server, --username, and --password options.

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 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 --type api --title Routes
apic create --type api --title Ascents
apic create --type product --title "Climb On" --apis "routes.yaml ascents.yaml"
apic config:set catalog=apic-catalog://mgmnthost.com/orgs/climbon/catalogs/sb
apic login --username some-user --password some-password --server mgmnthost.com
apic publish climb-on.yaml

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, retired, or archived. For example:

apic 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 sub-catalog, 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®.

apic catalogs:set catalog_name --spaces enabled

If Spaces are enabled for a Catalog, Products can be staged and published only to a Space within that Catalog. To publish to a Space, the --scope space option must be included in the publish command, for example:

apic publish --scope space product.yaml --space space --catalog catalog --organization organization --server server

where

• product is the name of the product that you want to publish.
• space is the name of the Space to publish to.
• catalog is name of the Catalog that contains the Space.
• organization is the name of the organization.
• server is the management server; portnumber is optional (default is 443).

apic publish --scope space product.yaml

Note: If the OpenAPI (Swagger 2.0) file that defines your API uses a $ref field to reference a fragment of OpenAPI (Swagger 2.0) 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 (Swagger 2.0) files.

Publishing Node.js applications

You can publish any Node.js application that has a properly-configured package.json file. Before publishing, you must install dependencies by running npm install. You must run the apic apps:publish command from the directory that contains package.json.

Publishing LoopBack APIs and applications

LoopBack projects contain both APIs and applications. Use the apic publish command described previously to publish the LoopBack APIs, and use the apic apps:publish command to publish the LoopBack application.

By default, a LoopBack project has default API and Product definitions in the project_dir/definitions directory. Publishing the API and Product artifacts is the same as any other set of API and Product artifacts except you can generate the artifacts directly from LoopBack models. For example:

apic loopback     # When prompted, enter "climbon" for project name and directory
cd climbon
apic create --type model           # Use as many times as required
apic loopback:property             # Use as many times as required
apic loopback:remote               # Use as many times as required
apic loopback:relation             # Use as many times as required
apic loopback:refresh              # (Re)generate the Product and API artifacts
apic config:set catalog=apic-catalog://mgmnthost.com/orgs/climbon/catalogs/sb
apic login --username some-user --password some-password --server mgmnthost.com
apic publish definitions/climbon-product.yaml

In addition to publishing the LoopBack APIs, you must also publish the associated LoopBack applications to an API Connect App that represents a Node.js run time. For example, add the following two commands to the above set to publish the LoopBack application:

apic config:set app=apic-app://mgmnthost.com/orgs/climbon/apps/sb-app
apic apps:publish