Migrating the APIs and Applications to a Different Environment

WSO2 API Manager (WSO2 API-M) allows you to maintain multiple environments running on the same WSO2 API-M version. This feature allows you to import and export applications or APIs between your environments. For example, if you have an application or API running in the development environment, you can import it and export to the test(QA) environment. Thereby, APIs and applications do not have to be created from scratch in different environments.

Getting Started

After running the CLI tool make sure to add an environment before you start working with the import/export CLI commands, because all APIs and applications need to be imported or exported to a specific environment.

Running the CLI tool
Adding an environment
Removing an environment
List environments

Running the CLI tool

Step 1 - Deploy the API import/export tool
Step 2- Run the CLI tool

Step 1 - Deploy the API import/export tool

Download the latest version of WSO2 API Manager from http://wso2.com/products/api-manager/.
Start the API Manager.
Download the latest WSO2 API import/export tool (api-import-export-2.5.0-v1.war) from here.

Note that the import/export tool attached is specific to this version of WSO2 API Manager.
Copy the downloaded api-import-export-2.5.0-v1.war file to the <API-M_HOME>/repository/deployment/server/webapps folder.
The file is automatically deployed as hot deployment is enabled.

Step 2- Run the CLI tool

Navigate to the API Management Tooling page - https://wso2.com/api-management/tooling/
Click Download under CLI.
Select a generated archive suitable for your platform (i.e., Mac, Windows, Linux) and extract it the CLI tool that you downloaded to a desired location and cd into it.
Navigate to the working directory where the executable CLI Tool resides.
Execute the following command to start the CLI tool.
```
./apimcli
```
Add the location of the extracted folder to your system's $PATH variable to be able to access the executable from anywhere.
For further instructions execute the following command.
apimcli --help

Adding an environment

You can add environments by either manually editing the $HOME/.wso2apimcli/main_config.yaml file or by running the following CLI command.

apimcli add-env

The directory structure for the configuration files ( $HOME/.wso2apimcli ) will be created upon execution of the apimcli command.

Make sure that WSO2 API Manager is started and that the CLI import/export tool is running.
Run the following CLI command to add an environment.

Removing an environment

Make sure that WSO2 API Manager is started and that the CLI import/export tool is running.
Run the following CLI command to remove an environment.

List environments

Make sure that WSO2 API Manager is started and that the CLI import/export tool is running.
Run the following CLI command to list the environments.
There are no flags for the following CLI command.
```
apimcli list envs
```

Migrating APIs to different environments

Exporting an API
Importing an API
Importing/exporting an API in a tenanted environment
List APIs

Exporting an API

Make sure that WSO2 API Manager is started and that the CLI import/export tool is running.
Run the following CLI command to export an existing API as a .zip archive.

Importing an API

You can use the archive created in the previous section to import APIs to an API Manager instance.

When you import an API, regardless the status of the imported API it will be added with the created state and you need to sign in to the Publisher and publish the API.

Make sure that WSO2 API Manager is started and that the CLI import/export tool is running.
For Secure Endpoint Enabled APIs:

If you have enabled secure endpoints when creating the API and your username or/and password differs in the two environments, please follow the steps below before importing the API.
1. Unzip the .zip archive created in the previous section.
2. Go to the PizzaShackAPI-1.0.0/Meta-information directory and open the api.json file.
3. Modify the endpointUTPassword with your endpoint password and save the api.json file.
4. Compress the PizzaShackAPI-1.0.0 folder to a folder named myExportedAPI.

Run the following CLI command to import an API.

You must add a parameter named --preserve-provider to the CLI command and set its value to false if the API is imported to a different domain than its exported one. This parameter sets the provider of the imported API to the user who is issuing the CLI command. Here's an example:

Troubleshooting

After importing, if the APIs are not visible in the API Publisher UI, do the following to re-index the artifacts in the registry.

Rename the <lastAccessTimeLocation> element in the <API-M_2.5.0_HOME>/repository/conf/registry.xml file. If you use a clustered/distributed API Manager setup, change the file in the API Publisher node. For example, change the /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime registry path to /_system/local/repository/components/org.wso2.carbon.registry/indexing/lastaccesstime_1.
Shut down the API Manager 2.5.0, backup and delete the <API-M_2.5.0_HOME>/solr directory.
For more information, see /wiki/spaces/AM250/pages/28345255.

Importing/exporting an API in a tenanted environment

To export an API from a tenant, follow the steps in Export an API. Use the tenant-specific encoded credentials in the CLI command. Here's an example:
To import the API in another tenant, follow the steps in Importing an API. Use the encoded credentials for this tenant in the CLI command. Here's an example:

When you import an API, regardless the status of the imported API it will be added with the created state and you need to sign in to the Publisher and publish the API.

Note that the --preserve-provider flag value should be set to false.

List APIs

Make sure that WSO2 API Manager is started and that the CLI import/export tool is running.
Run the following CLI command to list the APIs.

Migrating applications to different environments

Managing application lifecycle
Exporting an application
Importing an application
Importing applications in a single tenant environment
Importing applications in a multi-tenant environment
List apps

Managing application lifecycle

The lifecycle of an application could be defined as the stages of an application between the development and production environments. The feature facilitates to manage the application life cycle by allowing the user to migrate the applications within desired environments. The user should have admin permissions in order to use this.

Exporting an application

You can export applications in the API Store and download them as a zipped file.

Make sure that WSO2 API Manager is started and that the CLI import/export tool is running.
Run the following CLI command to export an existing application as a .zip archive.

The zipped file will be as follows:

<exported-Application>.zip
└── <Application-Name>
└── <Application-Name>.json

Importing an application

You can import an application to your environment as a zipped application. When you import an application as a zipped file, a new application is created within the target environment.

Make sure that WSO2 API Manager is started and that the CLI import/export tool is running.
Run the following CLI command to import an existing application as a .zip archive.

Importing applications in a single tenant environment

There are three options to import applications in a single tenant environment.

Application A in environment 1 is migrated to environment 2. Some APIs may not be available in environment 2 (API B in this case) and the relevant subscriptions are not added in such cases (skipped).
A different owner can be specified while importing an application to environment 2, without preserving the original user of environment 1.
The original owner of the application can be preserved when the application is imported to environment 2 by adding the --preserveOwner flag.

Importing applications in a multi-tenant environment

In a situation where an application has API subscriptions in different tenant domains, such subscriptions are added if the relevant APIs with the target tier, are available in the importing environment. Note that the provider of the API may not be the same in the importing environment.

List apps

Make sure that WSO2 API Manager is started and that the CLI import/export tool is running.
Run the following CLI command to list the apps.

Reset user

Make sure that WSO2 API Manager is started and that the CLI import/export tool is running.
Run the following CLI command to reset user details.

Check the version of the CLI

Make sure that WSO2 API Manager is started and that the CLI import/export tool is running.
Run the following CLI command to check the version of the CLI.
There are no flags for the following CLI command.

Set HTTP request timeout

Make sure that WSO2 API Manager is started and that the CLI import/export tool is running.
Run the following CLI command to set the HTTP request timeout.

Set export directory

Make sure that WSO2 API Manager is started and that the CLI import/export tool is running.
Run the following CLI command to set the export directory.

Understanding the API import/export tool

The API import/export tool uses a RESTful API, protected by basic authentication.

Only the following types of users are allowed to access the API import/export tool.

A user with the admin role.
A user with a role that has the API-M Admin, Login, and API Create permissions.
Click here to see a screen shot of the above listed permissions.

To allow access to the import/export feature only for a particular tenant, log in to WSO2 API Manager's Management Console and add the downloaded archive file as a web application to the server.

The 'admin' role is the default role which is specified in the Realm configuration in the <API-M-HOME>/repository/conf/user-mgt.xml file. It will be changed if you have changed the value of the <AdminRole> parameter as shown below.

<Realm>
        <Configuration>
		<AddAdmin>true</AddAdmin>
            <AdminRole>admin</AdminRole>            
         .....
       </Configuration>
</Realm>

The export functionality

The API export functionality retrieves the information required for the requested API from the registry and databases and generates a ZIP file, which the exporter can download. This exported ZIP file has the following structure:

Structure of the exported ZIP file

The structure of the ZIP file is explained below:

Sub directory/File	Description
Meta Information	`api.json:` contains all the basic information required for an API to be imported to another environment `swagger.json:` contains the API swagger definition
Documents	`docs.json:` contains the summary of all the documents available for the API Add the uploaded files for API documentation also
Image	Thumbnail image of the API
WSDL	WSDL file of the API
Sequences	The sequences available for the API

The import functionality

The import functionality uploads the exported ZIP file of the API to the target environment. It creates a new API with all the registry and database resources exported from the source environment. Note the following:

The lifecycle status of an imported API will always be CREATED even when the original API in the source environment has a different state. This is to enable the importer to modify the API before publishing it.
Tiers and sequences are provider-specific. If an exported tier is not already available in the imported environment, that tier is not added to the new environment. However, if an exported sequence is not available in the imported environment, it is added.
The importer can decide whether to keep the original provider’s name or replace it. Set the --preserve-provider flag to true to keep it. If you set it to false, the original provider is replaced by the user who is sending the CLI command.
Cross-tenant imports are not allowed by preserving the original provider. For example, if an API is exported from tenant A and imported to tenant B, the value of the --preserve-provider flag must always be false.