Page History

WSO2 API Cloud allows you to export and import APIs and applications between tenants using a CLI tool. For example, if you have an API running in a particular tenant (e.g., [email protected]@testorgs), you can use the CLI tool to export the API and then import it to another tenant environment (e.g., [email protected]@testorg1). Therefore, you do not have to take the time to create APIs and applications from scratch when you want to have the same APIs and applications in a different tenant.

Table of Contents

maxLevel	3
minLevel	3

Getting Started

Note
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.

Table of Content Zone

maxLevel	4
minLevel	4
location	top

Running the CLI tool

Table of Content Zone

location	top

Go to https://github.com/wso2/product-apim-tooling/releases/tag/v2.0.4.
Under the Assets section, click on a required installer depending on your operating system (i.e., MacOS, Linux, Windows). This downloads the appropriate CLI tool.
Once the download completes, extract the tool to a preferred location and cd into it.
Navigate to the working directory where the executable of the CLI tool resides.
Execute the following command to start the CLI tool.
Code Block
./apimcli
Add the location of the extracted folder to your system's $PATH variable to be able to access the executable from anywhere.
Note
For further instructions execute the following command.
Code Block
apimcli --help

Global flags for CLI tool

The following are some global flags that you can use with the CLI tool.

Code Block
--verbose Enable verbose logs (Provides more information on execution) --insecure, -k Allow connections to SSL sites without certs --help, -h Display information and example usage of a command

Adding the environment

You can add an environment by running the following CLI command.

Note
In API cloud importing and exporting of APIs and Applications take place between tenants as opposed to environments. Therefore, you need to only add one environment in the CLI tool. This environment will be used between tenants to call the endpoints of the API cloud.

Code Block
apimcli add-env

Make sure that the CLI import/export tool is running.

Run the following CLI command to add an environment.

Localtab Group

Localtab

active	true
id	Format-AddEvn
title	Command Format

Localtab Group

Localtab

active	true
id	LinuxFormatAddEnv
title	Linux Format

Code Block

apimcli add-env -n <environment-name> \
                        --registration <registration-endpoint> \
                        --apim <API-Manager-endpoint> \
                        --token <token-endpoint> \
                        --import-export <endpoint-for-environment> \
                        --admin <admin-REST-API-endpoint> \
                        --api_list <API-listing-REST-API-endpoint> \
                        --app_list <application-listing-REST-API-endpoint>

Localtab

id	MacFormatAddEnv
title	Mac Format

Code Block

apimcli add-env -n <environment-name> --registration <registration-endpoint> --apim <API-Manager-endpoint> --token <token-endpoint> --import-export <endpoint-for-environment> --admin <admin-REST-API-endpoint> --api_list <API-listing-REST-API-endpoint> --app_list <application-listing-REST-API-endpoint>

Flags:

Required flags:
- --name, -n : As we only need one environment when working with the API cloud, name the environment as follows: wso2apicloud
  There are no short flags for the following flags.
- --registration
- --apim
- --token
- --import-export
- --admin
- --api_list
- --app_list

Localtab

id	Example-AddEnv
title	Example

Localtab Group

Localtab

active	true
id	Linux1
title	Linux

Code Block

title	Example 1

apimcli add-env -n wso2apicloud \
                      --registration https://gateway.api.cloud.wso2.com/client-registration/register \
                      --apim https://gateway.api.cloud.wso2.com/pulisher \
                      --token https://gateway.api.cloud.wso2.com/token \
                      --import-export https://gateway.api.cloud.wso2.com/api-import-export \
                      --admin https://gateway.api.cloud.wso2.com/api/am/admin/ \
                      --api_list https://gateway.api.cloud.wso2.com/api/am/publisher/apis \
                      --app_list https://gateway.api.cloud.wso2.com/api/am/store/applications

Localtab

id	Mac OS
title	Mac OS

Code Block

title	Example 1

apimcli add-env -n wso2apicloud --registration https://gateway.api.cloud.wso2.com/client-registration/register --apim https://gateway.api.cloud.wso2.com/pulisher --token https://gateway.api.cloud.wso2.com/token --import-export https://gateway.api.cloud.wso2.com/api-import-export --admin https://gateway.api.cloud.wso2.com/api/am/admin/ --api_list https://gateway.api.cloud.wso2.com/api/am/publisher/apis --app_list https://gateway.api.cloud.wso2.com/api/am/store/applications

Localtab

id	ReponseAddEnv
title	Response

Localtab Group

Localtab

active	true
id	ResponseFormat
title	Response Format

Code Block
Successfully added environment '<environment-name>'

Localtab

id	ExampleResponse
title	Example Response

Code Block
Successfully added environment 'wso2apicloud'

Info

title	Troubleshooting

Why do I get the following error?

Code Block

[ERROR]: parsing /Users/<user-profile-name>/.wso2apimcli/env_keys_all.yaml
panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x0 pc=0x1343b82]

You get the above error if you have worked with two CLI tools. Carry out the following steps if you get the above error:

View the env_keys_all.yaml file and check if there are any NULL values.
Delete the env_keys_all.yaml file.
Execute the command that you initially executed.
For example if you got this error when trying to add an environment, then follow the steps mentioned under Adding an environment to reattempt to add the environment.

List environments

Make sure 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.

Localtab Group

Localtab

active	true
id	CommandENVList
title	Command

Code Block
apimcli list envs

Localtab

id	ResENVList
title	Response

Code Block

Environments available in file '/Users/kim/.wso2apimcli/main_config.yaml'
+--------------+---------------------------------------------+-----------------------------------------------------------------+-----------------------------------------+
|     NAME     |             PUBLISHER ENDPOINT              |                      REGISTRATION ENDPOINT                      |              TOKEN ENDPOINT              
+--------------+---------------------------------------------+-----------------------------------------------------------------+-----------------------------------------+
| wso2apicloud | https://gateway.api.cloud.wso2.com/pulisher | https://gateway.api.cloud.wso2.com/client-registration/register | https://gateway.api.cloud.wso2.com/token 
+--------------+---------------------------------------------+-----------------------------------------------------------------+-----------------------------------------+

Migrating APIs to a target tenant

Table of Content Zone

location	top

Exporting an API

Make sure that the CLI import/export tool is running.
Run the following CLI command and when prompted for credentials enter your user name and password. This exports an existing API as a .zip archive.
Tip
You need to specify the user name as <username>@<organization-key>. For example, [email protected]@testorgs

Localtab Group

Localtab

active	true
id	Format-exportAPI
title	Command Format

Code Block
apimcli export-api -n <API-name> -v <version> -r <provider> -e <environment> -k

Code Block
apimcli export-api --name <API-name> --version <version> --provider <provider> --environment <environment> --insecure

Flags:

Required flags:
- --name, -n
- --version, -v
- --provider, -r : The provider should be as follows: <username>@<organization-key> For example, [email protected]@testorgs
- --environment, -e : The name of the environment that you created in the API cloud, which is as follows: wso2apicloud
- --insecure, -k : This allows connections to SSL sites without certificates

Localtab

id	Example-exportAPI
title	Example

Code Block
apimcli export-api -n PhoneVerification -v 1.0.0 -r [email protected]@testorgs -e wso2apicloud -k

Localtab

id	Reponse-exportAPI
title	Response

Code Block
Succesfully exported API! Find the exported API at /Users/kim/.wso2apimcli/exported/apis/wso2apicloud/PhoneVerification_1.0.0.zip

Importing an API

Multiexcerpt

MultiExcerptName	importAPIcreated

Note
When you import an API, regardless of 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.

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

Make sure that the CLI import/export tool is running.

Note

title	For Secure Endpoint Enabled APIs:

If you have enabled secure endpoints when creating the API and your user name 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 <API-name-version>/Meta-information directory and open the api.json file.
For example, PhoneVerification_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 PhoneVerification_1.0.0 folder to a folder named myExportedAPI.

Run the following CLI command and when prompted for credentials enter your user name and password. This imports an API.

Tip
You need to specify the user name as `<username>@<organization-key>`. For example, `[email protected]@testorgs`

Localtab Group

Localtab

active	true
id	Format-importAPI
title	Command Format

Code Block
apimcli import-api -f <environment>/<file> -e <environment> --preserve-provider <preserve_provider> -k

Code Block
apimcli import-api --file <environment>/<file> --environment <environment> --preserve-provider <preserve_provider> --insecure

Flags:

Required flags:
- --file, -f : The file path of the exported API. For example, if your file path is /Users/kim/.wso2apimcli/exported/apis/wso2apicloud/PhoneVerification_1.0.0.zip., then you need to enter wso2apicloud/PhoneVerification_1.0.0.zip as the value for this flag.
- --environment, -e : The name of the environment that you created in the API cloud, which is as follows: wso2apicloud
- --insecure, -k : This allows connections to SSL sites without certificates
- --preserve-provider : The importer can decide whether to keep the original provider’s name or replace it. When working with the API cloud, you need to set this value to false because you need to import the API from a different tenant and replace the original tenant's details.

Localtab

id	Example-importAPI
title	Example

Code Block
apimcli import-api -f wso2apicloud/PhoneVerification_1.0.0.zip -e wso2apicloud --preserve-provider=false -k

Localtab

id	ResponseImport
title	Response

Code Block

title	Sample Response

ZipFilePath: /Users/kim/.wso2apimcli/exported/apis/wso2apicloud/PhoneVerification_1.0.0.zip
Successfully imported API 'wso2apicloud/PhoneVerification_1.0.0.zip'
Succesfully imported API!

List APIs

Note
If you happen to list APIs that belong to a particular tenant (e.g., `[email protected]@testorg1`) and then you decide to list APIs that belong to another tenant (e.g., `[email protected]@testorgs`), you need to first reset the user before listing APIs again.

Make sure that the CLI import/export tool is running.
Run the following CLI command and when prompted for credentials enter your user name and password. This lists your APIs.
Tip
You need to specify the user name as <username>@<organization-key>. For example, [email protected]@testorgs

Localtab Group

Localtab

active	true
id	Format-listAPI
title	Command Format

Code Block
apimcli list apis -e <environment> -k

Code Block
apimcli list apis --environment <environment> --insecure

Flags:

Required flags:
- --environment, -e : The name of the environment that you created in the API cloud, which is as follows: wso2apicloud
- --insecure, -k

Localtab

id	Example-listAPI
title	Example

Code Block
apimcli list apis -e wso2apicloud -k

Localtab

id	Response-listAPI
title	Response

Code Block

Environment: wso2apicloud
No. of APIs: 2
+-------------------+---------+-------------------------+-----------+-----------------------+--------------------------------------+
|       NAME        | VERSION |         CONTEXT         |  STATUS   |    PROVIDER           |                  ID                  |
+-------------------+---------+-------------------------+-----------+-----------------------+--------------------------------------+
| PhoneVerification | 1.0.0   | /t/testorg1/phoneverify | CREATED   | [email protected]@testorg1 | e72e2291-d135-4a1c-ba03-9278ede71075 |
| WorldBank         | 1.0.0   | /t/testorg1/wb          | PUBLISHED | [email protected]@testorg1 | b89a62a7-c27a-4fcc-9d24-0db0ee63d289 |
+-------------------+---------+-------------------------+-----------+-----------------------+--------------------------------------+

Migrating applications to a target tenant

Table of Content Zone

location	top

Exporting an application

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

Make sure that the CLI import/export tool is running.
Run the following CLI command and when prompted for credentials enter your user name and password. This exports an existing application as a .zip archive.
Tip
You need to specify the user name as <username>@<organization-key>. For example, [email protected]@testorgs

Localtab Group

Localtab

active	true
id	Format-exportApp
title	Command Format

Code Block
apimcli export-app -n <application-name> -o <owner> -e <environment> -k

Code Block
apimcli export-app --name <application-name> --owner <owner> --environment <environment> --insecure

Flags:

Required flags:
- --name, -n
- --owner, -o : The owner should be as follows: <username>@<organization-key> For example, [email protected]@testorgs
- --environment, -e : The name of the environment that you created in the API cloud, which is as follows: wso2apicloud
- --insecure, -k : This allows connections to SSL sites without certificates

Localtab

id	Example-exportapp
title	Example

Code Block
apimcli export-app -n TestApp -o [email protected]@testorg1 -e wso2apicloud -k

Localtab

id	Response-exportapp
title	Response

Code Block
Succesfully exported Application! Find the exported Application at /Users/kim/.wso2apimcli/exported/apps/wso2apicloud/[email protected]@testorg1_TestApp.zip

The zipped file will be as follows:

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

Importing an application

Note
If you have been executing previous commands specifying credentials of a particular tenant and now you want to run the import application CLI command for another tenant, then you need to first reset the user before running the import an application command.

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

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

Localtab Group

Localtab

active	true
id	Format-importApp
title	Command Format

Code Block
apimcli import-app -f <environment>/<file> -e <environment> -s <skip_subscriptions> -o <owner> -r <preserve_owner> -k

Code Block
apimcli import-app --file <environment>/<file> --environment <environment> --skipSubscriptions <skip_subscriptions> --owner <owner> --preserveOwner <preserve_owner> --insecure

Flags:

Required flags
- --file, -f : The file path of the exported App. For example, if your file path is /Users/kim/.wso2apimcli/exported/apps/wso2apicloud/[email protected]@testorg1_TestApp.zip then you need to add wso2apicloud/[email protected][email protected]_TestApp.zip as the value for this flag.
- --environment, -e : The name of the environment that you created in the API cloud, which is as follows: wso2apicloud
- --insecure, -k : This allows connections to SSL sites without certificates
Optional flags--skipSubscriptions, -s You can opt to skip importing the subscriptions of the application by defining this flag. This parameter is set to false by default. --owner, -o The owner of the imported application can be specified by providing a valid user name based on your preference. The application importer can set the preferred owner’s user name as the value of the --owner or -o flag. --preserveOwner, -r You can also import the application by preserving the application owner information, based on the previous tenant. The application importer can add the --preserveOwner or -r flag in order to define that this flag is set to true. This parameter is set to false by default. Therefore, the default value is used when you do not define this flag. If you import the application without specifying any of the optional flags, you will be added as the owner of the application in the imported environment. If both the --owner and the --preserveOwner flags are set, then the --owner flag gets higher priority over the --preserveOwner flag.

Localtab

id	Example-importapp
title	Example

Code Block

apimcli import-app -f wso2apicloud/[email protected]@testorg1_TestApp.zip -e wso2apicloud -o [email protected]@testorgs --preserveOwner --skipSubscriptions -u [email protected]@testorgs -p admin123# -k

Localtab

id	Reponse-importapp
title	Response

Code Block

ZipFilePath: /Users/kim/.wso2apimcli/exported/apps/wso2apicloud/[email protected]@testorg1_TestApp.zip
Completed importing the Application 'wso2apicloud/[email protected]@testorg1_TestApp.zip'
Succesfully imported Application!

List apps

Make sure that the CLI import/export tool is running.
Run the following CLI command and when prompted for credentials enter your user name and password. This lists your apps.
Tip
You need to specify the user name as <username>@<organization-key>. For example, [email protected]@testorgs

Localtab Group

Localtab

active	true
id	Format-listApps
title	Command Format

Code Block
apimcli list apps -e <environment> -o <owner> -k

Code Block
apimcli list apps --environment <environment> --owner <owner> --insecure

Flags:

Required flags
- --environment, -e : The name of the environment that you created in the API cloud, which is as follows: wso2apicloud
- --owner, -o
- --insecure, -k : This allows connections to SSL sites without certificates

Localtab

id	Example-listApps
title	Example

Code Block
apimcli list apps -e wso2apicloud -o admin -k

Localtab

id	Response-listApps
title	Response

Code Block

Environment: wso2apicloud
No. of Applications: 2
+--------------------------------------+--------------------+-------+----------+----------+
|                  ID                  |        NAME        | OWNER |  STATUS  | GROUP-ID |
+--------------------------------------+--------------------+-------+----------+----------+
| e13b5bcf-dee5-48fe-9f23-bf46fc17a378 | DefaultApplication |       | APPROVED |          |
| 153ad3d3-fa26-4dda-af54-27eee3327848 | TestApp            |       | APPROVED |          |
+--------------------------------------+--------------------+-------+----------+----------+

Reset user

If you want to list APIs or applications that belong to a particular tenant, you need to first reset the user before listing APIs or applications for the particular tenant.

Make sure that the CLI import/export tool is running.

Run the following CLI command to reset user details.

Localtab Group

Localtab

active	true
id	Format-ResetUser
title	Command Format

Code Block
apimcli reset-user -e <environment>

Code Block
apimcli reset-user --environment <environment>

Flags:

Required flags
- --environment, -e : The name of the environment that you created in the API cloud, which is as follows: wso2apicloud

Localtab

id	Example-ResetUser
title	Example

Code Block
apimcli reset-user -e wso2apicloud

Localtab

id	ResponseClearUser
title	Response

Code Block
Successfully cleared user data for environment: wso2apicloud

Check the version of the CLI

Make sure 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.
Localtab Group
Localtab
active true
id Format-CLIver
title Command
Code Block
apimcli version
Localtab
id Example-CLIver
title Example
Code Block
apimcli Version: 1.1.0

Set HTTP request timeout

Make sure that the CLI import/export tool is running.

Run the following CLI command to set the HTTP request timeout.

Localtab Group

Localtab

active	true
id	Format-RstTime
title	Command Format

Code Block
apimcli set --http-request-timeout <http-request-timeout>

Flags:

--http-request-timeout

Localtab

id	Example-RstTime
title	Example

Code Block
apimcli set --http-request-timeout 10000

Set export directory

Make sure that the CLI import/export tool is running.

Run the following CLI command to the change the default location of the export directory.

Localtab Group

Localtab

active	true
id	Format-expDir
title	Command Format

Code Block
apimcli set --export-directory <export-directory-path>

Flags:

--export-directory

Localtab

id	Example-expDir
title	Example

Code Block
apimcli set --export-directory /Users/kim/Downloads/MyExports

Understanding the API import/export tool

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

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 life cycle 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. When working with the API cloud you need to set this flag to false, because exporting and importing happen between tenants in the API cloud.
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.

Versions Compared

Old Version 19

New Version Current

Key

Getting Started

Running the CLI tool

Global flags for CLI tool

Adding the environment

List environments

Migrating APIs to a target tenant

Exporting an API

Importing an API

List APIs

Migrating applications to a target tenant

Exporting an application

Importing an application

List apps

Reset user

Check the version of the CLI

Set HTTP request timeout

Set export directory

Understanding the API import/export tool

The export functionality

The import functionality