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., kim@wso2.com@testorgs), you can use the CLI tool to export the API and then import it to another tenant environment (e.g., kim@wso2.com@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.
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 |
---|
|
Table of Content Zone |
---|
| - 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. 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. |
|
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 |
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 |
---|
| 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 |
---|
| Code Block |
---|
| 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 |
---|
| 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.
|
- 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
+--------------+---------------------------------------------+-----------------------------------------------------------------+-----------------------------------------+ |
|
|
|
Table of Content Zone |
---|
|
- 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, kim@wso2.com@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, kim@wso2.com@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 kim@wso2.com@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 |
|
|
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. |
Note |
---|
If you happen to list APIs that belong to a particular tenant (e.g., kim@wso2.com@testorg1 ) and then you decide to list APIs that belong to another tenant (e.g., kim@wso2.com@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, kim@wso2.com@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 | kim@wso2.com@testorg1 | e72e2291-d135-4a1c-ba03-9278ede71075 |
| WorldBank | 1.0.0 | /t/testorg1/wb | PUBLISHED | kim@wso2.com@testorg1 | b89a62a7-c27a-4fcc-9d24-0db0ee63d289 |
+-------------------+---------+-------------------------+-----------+-----------------------+--------------------------------------+ |
|
|
|
Table of Content Zone |
---|
|
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, kim@wso2.com@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, kim@wso2.com@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 kim@wso2.com@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/kim@wso2.com@testorg1_TestApp.zip |
|
|
The zipped file will be as follows: <exported-Application>.zip
└── <Application-Name>
└── <Application-Name>.json
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/kim@wso2.com@testorg1_TestApp.zip
then you need to add wso2apicloud/kim@wso2.com@testorg1_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/kim@wso2.com@testorg1_TestApp.zip -e wso2apicloud -o kim@wso2.com@testorgs --preserveOwner --skipSubscriptions -u kim@wso2.com@testorgs -p admin123# -k |
|
Localtab |
---|
id | Reponse-importapp |
---|
title | Response |
---|
| Code Block |
---|
ZipFilePath: /Users/kim/.wso2apimcli/exported/apps/wso2apicloud/kim@wso2.com@testorg1_TestApp.zip
Completed importing the Application 'wso2apicloud/kim@wso2.com@testorg1_TestApp.zip'
Succesfully imported Application! |
|
|
- 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, kim@wso2.com@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 | |
+--------------------------------------+--------------------+-------+----------+----------+ |
|
|
|
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 |
|
|
- 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 |
|
|
- 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: |
Localtab |
---|
id | Example-RstTime |
---|
title | Example |
---|
| Code Block |
---|
apimcli set --http-request-timeout 10000 |
|
|
- 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: |
Localtab |
---|
id | Example-expDir |
---|
title | Example |
---|
| Code Block |
---|
apimcli set --export-directory /Users/kim/Downloads/MyExports |
|
|
The API import/export tool uses a RESTful API, protected by basic authentication.
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:

The structure of the ZIP file is explained below:
Sub directory/File | Description |
---|
Meta Information | |
Documents | |
Image | Thumbnail image of the API |
WSDL | WSDL file of the API |
Sequences | The sequences available for the API |
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
.