Promote managed APIs between environments

Overview

When APIs have been registered in API Manager, you can promote them directly between environments using the API Manager export/import mechanism. This exports registered APIs in JSON format, which you can then import into API Manager as required. For more details, see the Manage front-end REST API lifecycle.

The following approaches to promoting managed APIs are also available:

  • Use the apimanager-promote script to automatically promote APIs between environments with zero downtime for DevOps.
  • Use a promotion policy that you have configured in Policy Studio to automate promotion between environments.
  • When APIs have been developed using Policy Studio, you can also promote them between environments using the API Gateway mechanism for promotion and deployment of standard API Gateway configuration.

This topic describes each of these approaches to API promotion.

Promote registered APIs with zero downtime using a script

The apimanager-promote script enables you to:

  • Promote APIs and client applications registered in API Manager to another environment with zero downtime. For example, this ensures that you will not lose service due to any APIs that are unpublished.
  • Perform automatic bulk import of APIs and applications previously exported using the API Manager REST API or web console.
  • Ensure that pre-configured credentials continue to work between environments.
  • Export a subset of APIs and applications and re-import with customized settings in a properties file.
  • Handle updates of any conflicting APIs, applications, or application credentials without causing downtime for any published APIs.

How to use the apimanager-promote script

When using the apimanager-promote script, the high-level steps are as follows:

  1. Export the APIs and applications that you wish to promote from API Manager (as a .dat file in JSON format). For example, select the front-end APIs that you wish to export, and click Manage selected > Export API collection. For more details, see Manage front-end REST API lifecycle and Manage the client application lifecycle.
  2. Alternatively, you can export using the API Manager REST API. For more details, see API Manager REST APIs.
  3. Create your promotion.properties file to specify how your APIs and applications are promoted. See Generate your promotion.properties file.
  4. Place your exported API and application files (.dat) and your generated promotion.properties file in the same directory.
  5. Note   You must ensure that the respective files names are api-*.dat, application-*.dat, and promotion.properties, and change the file names if necessary.
  1. Run the apimanager-promote script to import the APIs into the target API Manager environment.
  2. This script is available in the following directory:

Run the apimanager-promote command

You must specify the target environment that you wish to promote into, your API administrator credentials, along with your source API data files and promotion properties file. For example:

Note   The path/to/my_api_data directory must include the exported .dat file for the source APIs (and optional applications if exported) and your promotion.properties file.

Specify apimanager-promote command options

You can specify the following command options:

Command option Description
-? --help Print help message and exit.
-f , --passfile <arg> Specify an API administrator password file.
-p , --password <arg> Specify an API administrator password.
-t , --target <arg> Specify the target API Manager environment URL.
--template Print out the promotion.properties template file to help specify the required data.
-u,--username <arg> Specify the API administrator user name.

Generate your promotion.properties file

You must create a promotion.properties file to specify options for the APIs and applications to be promoted. For example, this enables you to specify how to manage any conflicts and an optional virtual host for the target environment.

You can use the apimanager-promote --template command to generate a default properties file, which you can then customize as needed. For example:

Note   You must ensure that the target organizations specified in the promotion.properties file already exist in that instance before running the apimanager-promote command.

The promotion properties are described as follows:

Property Description
organization.apipromotion.import Specify the target development organization that all the APIs are imported into (for example, the default API Development organization).
organization.target Specify the target consumer organization that all the client applications are imported into. This organization is also given access to all the imported APIs (for example, the Community organization).
api.conflict.upgrade Specify whether to promote an existing API if there is a conflict in the development organization (true or false).
application.conflict.upgrade Specify whether to promote an existing application if there is a conflict in the consumer organization (true or false).
application.apikey.upgrade Specify whether to promote an existing API key if there is a conflict in the consumer organization (true or false).
application.oauthclient.upgrade Specify whether to promote an existing OAuth client application if there is a conflict in the consumer organization (true or false).
application.oauthresource.upgrade Specify whether to promote an existing OAuth resource if there is a conflict in the consumer organization (true or false).
api.publish.virtualhost Specify an optional virtual host name and port on which the promoted APIs are available. The host name should be DNS resolvable.
api.unpublished.remove

Specify whether to remove an old unpubished API from the development organization (true or false). This only applies when an upgrade occurs. For example, if there is a conflict and api.conflict.upgrade is set to true, this results in two APIs (existing and upgraded). The api.unpublished.remove option specifies whether to keep or delete the existing API that has been unpublished.

Tip   After running the apimanager-promote command, press F5 to reload the API Manager web console in the target environment.

Promote registered APIs using a promotion policy

APIs and applications registered using API Manager can be exported from one API Manager environment and imported into another API Manager environment using a file-based package (.dat file in JSON format). For example, this enables APIs to be promoted from a sandbox API group where client applications are developed and tested to the production API group. You can use a custom promotion policy that has already been developed in Policy Studio to automate this process in API Manager.

Note   If you use a custom promotion policy, you must also promote this policy as part of the standard API Gateway configuration. For more details, see Promote APIs developed in Policy Studio.

Create the promotion policy in Policy Studio

You must first create your custom promotion policy in Policy Studio to import APIs into a target environment. For example, the following promotion policy is based on the proxies/import method provided in the API Manager REST API:

API Manager Promotion Policy

This policy imports a previously exported API as follows:

  • If the API was exported using a password, the file is encrypted, and a password must be set to decrypt.
  • The target API Manager environment is specified by setting the target organization ID.
  • The import creates a virtualized API and all the back-end API definitions necessary for the front-end API in JSON format.
  • This approach is similar to the proxies/importFromUrl method except that it supports traditional form-based file upload to the target environment using multipart/form-data.

For more details on the on the proxies/import method, see API Manager REST APIs.

Tip   You can also use the Set Attribute filter in your promotion policy to configure the errorMessage message attribute with a meaningful error message. For example, when used in conjunction with a False filter, this message can then be displayed in API Manager if the API promotion policy fails.

For more details on how to create policies, see the API Gateway Policy Developer Guide.

Enable the promotion policy in Policy Studio

To enable your custom promotion policy in Policy Studio, select Server Settings > API Manager > API Promotion in the Policy Studio tree. For more details, see Configure API Manager settings in Policy Studio.

Enable the promotion policy in API Manager

When you have configured and deployed a promotion policy in Policy Studio, you must also then enable the policy in API Manager. You can do this by selecting Settings > API Manager settings > API REGISTRATION > API promotion via policy. A Promote API option is then added to the Frontend API management menu when you log in again. For more details, see Configure web-based settings in API Manager.

For details of onboarding a client application from sandbox APIs to production APIs, see Deploy sandbox and production APIs.

Promote APIs developed in Policy Studio

APIs created with the REST API development wizard in Policy Studio are part of the standard API Gateway configuration. This means that you can promote APIs between environments using the API Gateway mechanism for promotion and deployment of API Gateway configuration (using .fed, .pol, and .env packages). For example, you can use this mechanism to promote APIs from a testing environment to a production environment and to handle differences between each environment.

For more details on the API Gateway mechanism for promoting configuration between environments, see the API Gateway DevOps Deployment Guide. For details of onboarding a client application from sandbox APIs to production APIs, see Deploy sandbox and production APIs.

Related Links