Try WSO2 Cloud for Free
Sign in

All docs This doc
||
Skip to end of metadata
Go to start of metadata

WSO2 API Manager (WSO2 API-M) allows you to export and import APIs between tenants using the CLI Tool. For example, if you have an application or API running in a tenant (e.g., kim@wso2.com@testorgs) , you can export it and import it to another tenant environment (e.g., kim@wso2.com@testorg1). Thereby, APIs and applications do not have to be created from scratch when working with different tenants on the API cloud.

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

  1. Navigate to the API Management Tooling page - https://wso2.com/api-management/tooling/
  2. Click Download under CLI.
  3. 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.

  4. Navigate to the working directory where the executable of the CLI tool resides.

  5. Execute the following command to start the CLI tool.

    ./apimcli
  6. 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
Global flags for CLI tool

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

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

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.

apimcli add-env
  1. Make sure that the CLI import/export tool is running. 
  2. Run the following CLI command to add an environment.

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

    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
    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
    Successfully added environment '<environment-name>'
    Successfully added environment 'wso2apicloud'

    Troubleshooting

    Why do I get the following error?

    [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:

    1. View the env_keys_all.yaml file and check if there are any NULL values.

    2. Delete the env_keys_all.yaml file.

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

  1. Make sure that the CLI import/export tool is running.
  2. Run the following CLI command to list the environments.
    There are no flags for the following CLI command.

    apimcli list envs
    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

Exporting an API

  1. Make sure that the CLI import/export tool is running.
  2. Run the following CLI command to export an existing API as a .zip archive.
apimcli export-api -n <API-name> -v <version> -r <provider> -e <environment> -u <username> -p <password> -k
apimcli export-api --name <API-name> --version <version> --provider <provider> --environment <environment> --username <username> --password <password> --insecure

The username and password are optional flags. You will be prompted to enter your credentials if you do not provide these flags.

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
  • Optional flags:

    • --username, -u : The username should be added as follows: <username>@<organization-key>
      For example, kim@wso2.com@testorgs
    • --password, -p

apimcli export-api -n PhoneVerification -v 1.0.0 -r kim@wso2.com@testorgs -e wso2apicloud -u kim@wso2.com@testorgs -p admin123# -k
Succesfully exported API!
Find the exported API at /Users/kim/.wso2apimcli/exported/apis/wso2apicloud/PhoneVerification_1.0.0.zip

Importing an API

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.

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

  1. Make sure 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 <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 to import an API.

    apimcli import-api -f <environment>/<file> -e <environment> -u <username> -p <password> --preserve-provider <preserve_provider> -k
    apimcli import-api --file <environment>/<file> --environment <environment> --username <username> --password <password> --preserve-provider <preserve_provider> --insecure

    The username and password are optional flags. You will be prompted to enter your credentials if you do not provide these flags.

    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.
    • Optional flags:
      • --username, -u : The username should be added as follows: <username>@<organization-key>
        For example, kim@wso2.com@testorgs
      • --password, -p
    apimcli import-api -f wso2apicloud/PhoneVerification_1.0.0.zip -e wso2apicloud -u kim@wso2.com@testorgs -p admin123# --preserve-provider=false -k
    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

If you happen to list APIs that belong to one tenant (e.g., kim@wso2.com@testorg1) and then you decide to list APIs that belong to the other tenant (e.g., kim@wso2.com@testorgs), you need to first reset the user before listing APIs again.


  1. Make sure that the CLI import/export tool is running.
  2. Run the following CLI command to list the APIs.
apimcli list apis -e <environment> -u <username> -p <password> -k            
apimcli list apis --environment <environment> --username <username> --password <password> --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
  • Optional flags:

    • --username, -u : The username should be added as follows: <username>@<organization-key>
      For example, kim@wso2.com@testorgs
    • --password, -p

apimcli list apis -e wso2apicloud -u kim@wso2.com@testorg1 -p admin123# -k
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 |
+-------------------+---------+-------------------------+-----------+-----------------------+--------------------------------------+

Migrating applications to a target tenant

Exporting an application

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

  1. Make sure that the CLI import/export tool is running.
  2. Run the following CLI command to export an existing application as a .zip archive.
apimcli export-app -n <application-name> -o <owner> -e <environment> -u <username> -p <password> -k
apimcli export-app --name <application-name> --owner <owner> --environment <environment> --username <username> --password <password> --insecure

The username and password are optional flags. You will be prompted to enter your credentials if you do not provide these flags.

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
  • Optional flags:
    • --username, -u : The username should be added as follows: <username>@<organization-key>
      For example, kim@wso2.com@testorgs
    • --password, -p
apimcli export-app -n TestApp -o kim@wso2.com@testorg1 -e wso2apicloud -u kim@wso2.com@testorg1 -p admin123# -k
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

Importing an application

Prior to executing this command if you have executed commands using one of the tenant's credentials and then change the tenant details to run the import an application CLI command, 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.

  1. Make sure that the CLI import/export tool is running.
  2. Run the following CLI command to import an existing application as a .zip archive.
apimcli import-app -f <environment>/<file> -e <environment> -s <skip_subscriptions> -o <owner> -r <preserve_owner> -k            
apimcli import-app --file <environment>/<file> --environment <environment> --skipSubscriptions <skip_subscriptions> --owner <owner> --preserveOwner <preserve_owner> --insecure

The username and password are optional flags. You will be prompted to enter your credentials if you do not provide these flags.

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 an username of a valid user based on your preference. The application importer can set the preferred owner’s username 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.
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
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!


List apps

  1. Make sure that the CLI import/export tool is running.
  2. Run the following CLI command to list the apps.
apimcli list apps -e <environment> -u <username> -o <owner> -p <password> -k             
apimcli list apps --environment <environment> --owner <owner> --username <username> --password <password> --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
  • Optional flags
    • --username, -u : The username should be added as follows: <username>@<organization-key>
      For example, kim@wso2.com@testorgs
    • --password, -p
apimcli list apps -e wso2apicloud -o admin -u kim@wso2.com@testorgs -p admin123# -k
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 are list APIs or applications that belong to one tenant, you need to first reset the user before listing APIs or applications for the other tenant.

  1. Make sure that the CLI import/export tool is running.
  2. Run the following CLI command to reset user details.

    apimcli reset-user -e <environment>
    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
    apimcli reset-user -e wso2apicloud
    Successfully cleared user data for environment: wso2apicloud

Check the version of the CLI

  1. Make sure that the CLI import/export tool is running.
  2. Run the following CLI command to check the version of the CLI.
    There are no flags for the following CLI command.

    apimcli version
    apimcli Version: 1.1.0

Set HTTP request timeout

  1. Make sure that the CLI import/export tool is running.
  2. Run the following CLI command to set the HTTP request timeout.

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

    Flags:

    • --http-request-timeout

    apimcli set --http-request-timeout 10000

Set export directory

  1. Make sure that the CLI import/export tool is running.
  2. Run the following CLI command to the change the default location of the export directory.

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

    Flags:

    • --export-directory

    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/FileDescription

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

ImageThumbnail image of the API
WSDLWSDL file of the API
SequencesThe 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.
  • No labels