This documentation is for WSO2 API Manager 2.6.0. View documentation for the latest release.

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

Note that the instructions given below are applicable only if your WSO2 API Manager distribution has WUM updates.

To know more about WUM updates see, Updating WSO2 API Manager.


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 APIs between your environments. For example, if you have an API running in the development environment, you can import it and export to the test(QA) environment. Thereby, APIs 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

Step 1 - Deploy the API import/export tool

  1. Download the latest version of WSO2 API Manager from http://wso2.com/products/api-manager/.

  2. Start WSO2 API Manager.
  3. Download the latest WSO2 API import/export tool (api-import-export-2.6.0-v17.war) from  here.

    • Note that the import/export tool attached is specific to this version of WSO2 API Manager.

    • Make sure to delete all previous versions of the web app (e.g., api-import-export-2.6.0-v17.war), both the compressed and the extracted files, before copying over the new web app.

    • This version of the API Import and Export web application is compatible with the WSO2 WUM updates from July 8, 2019, onwards. For more information on updating WSO2 API Manager, see Updating WSO2 API Manager.
    • The previous version of the web application which is compatible with WUM updates that are prior to the above-mentioned date can be download from here.
    • Note that API update support in the targeted environment is available only with the api-import-export-2.6.0-v14.war version onwards.
  4. Copy the downloaded api-import-export-2.6.0-v17.war file to the <API-M_HOME>/repository/deployment/server/webapps folder.
    The file is automatically deployed as hot deployment is enabled.


Step 2 - Optionally, set the proxy environment variables for CLI

You can set proxy related HTTP_PROXY, HTTPS_PROXY, http_proxy, and https_proxy standard environment variables, with or without basic authentication as shown below to send the requests initiated from CLI via a proxy server. After one of the following environment variables is set in your environment where CLI is used, all the requests will go through the proxy server specified.

export HTTP_PROXY="http://<host-name>:<port>"
export HTTPS_PROXY="https://<host-name>:<port>"
export http_proxy="http://<host-name>:<port>"
export https_proxy="https://<host-name>:<port>"
export HTTP_PROXY="http://<username>:<password>@<host-name>:<port>"
export HTTPS_PROXY="https://<username>:<password>@<host-name>:<port>"
export http_proxy="http://<username>:<password>@<host-name>:<port>"
export https_proxy="https://<username>:<password>@<host-name>:<port>"
export HTTP_PROXY="http://localhost:3128"
export HTTPS_PROXY="https://localhost:3128"
export http_proxy="http://localhost:3128"
export https_proxy="https://localhost:3128"
export HTTP_PROXY="http://testuser:password@localhost:3128"
export HTTPS_PROXY="https://testuser:password@localhost:3128"
export http_proxy="http://testuser:password@localhost:3128"
export https_proxy="https://testuser:password@localhost:3128"


In conjunction with the above proxy configurations, calls from the CLI to particular hosts that need to bypass proxies can be configured via either the NO_PROXY or no_proxy environment variables.

export NO_PROXY="https://<host-name>:<port>"
export no_proxy="https://<host-name>:<port>"
export NO_PROXY="https://localhost:3128"
export no_proxy="https://localhost:3128"


Step 3 - Run the CLI tool
  1. Download API Controller based on your preferred platform (i.e., Mac, Windows, Linux).

  2. Extract the downloaded archive containing the CLI Tool to a preferred location and navigate to it from the terminal (using cd ).
  3. Navigate to the working directory where the executable CLI Tool resides.
  4. Execute the following command to start the CLI tool.

    ./apimcli
  5. 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

Migrating APIs to different environments

Exporting an API

  1. Make sure that WSO2 API Manager is started and 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> -k
apimcli export-api --name <API-name> --version <version> --provider <provider> --environment <environment> --insecure


Flags:

  • Required flags:
    • --name, -n
    • --version, -v
    • --provider, -r
    • --environment, -e
    • --insecure, -k : This allows connections to SSL sites without certificates
apimcli export-api -n PhoneVerification -v 1.0.0 -r admin -e dev -k
Succesfully exported API!
Find the exported API at /Users/kim/.wso2apimcli/exported/apis/dev/PhoneVerification_1.0.0.zip

Importing an API

The lifecycle status of the API is preserved when importing/exporting the API as the --preserveStatus flag is set to true by default.

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

  1. 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 <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> -k
    apimcli import-api --file <environment>/<file> --environment <environment> --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/dev/PhoneVerification_1.0.0.zip., then you need to enter dev/PhoneVerification_1.0.0.zip as the value for this flag.
      • --environment, -e : The environment to which you what to import the API to.
      • --insecure, -k : This allows connections to SSL sites without certificates
    • Optional flags:
      • --preserveStatus : Preserves the lifecycle state of an API when importing/exporting. The default value is set to true. If this value is set to false the API will be exported in the CREATED status. 
        As the --preserveStatus is set to true by default the status of the API will be preserved when the API is exported. Therefore when the API is imported it will be imported to the new environment with the correct lifecycle state.
    apimcli import-api -f dev/PhoneVerification_1.0.0.zip -e production -u admin -p admin -k
    Sample Response
    ZipFilePath: /Users/kim/.wso2apimcli/exported/apis/dev/PhoneVerification_1.0.0.zip
    Successfully imported API 'dev/PhoneVerification_1.0.0.zip'
    Succesfully imported 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:

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

    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:
      • --insecure, -k : This allows connections to SSL sites without certificates
      • --file, -f
      • --environment, -e : The environment to which you what to import the API to.
      • --preserve-provider (This does not have a short flag)
    • Optional flags:
      • --username, -u
      • --password, -p
    apimcli import-api -k -f dev/PhoneVerification_1.0.0.zip -e production -u admin -p admin --preserve-provider=false

    The --preserve-provider flag is used to decide whether to keep the actual Provider as the provider of the API or change the provider to the user who is importing the API to a different environment.

    As an example, If --preserve-provider is set to true, when importing an API created by user-1 in environment-1 will be preserved as the provider when and after importing that API to environment-2 by user-2. If --preserve-provider is set to false, when importing that API created by user-1 to the environment-2, the provider will be changed (not preserved) to user-2 who is importing the API.

    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.

    1. Rename the <lastAccessTimeLocation> element in the <API-M_2.6.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.

    2. Shut down the API Manager 2.6.0, backup and delete the <API-M_2.6.0_HOME>/solr directory.

      For more information, see Upgrading the API Manager to 2.6.0.

Importing/exporting an API in a tenanted environment

The environments that you create will be common to the admin and the tenants. Therefore, you do not need to create environments again when exporting and importing APIs between tenanted environments.


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

    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
      • --environment, -e : The environment to which you what to export the API to.
      • --insecure, -k : This allows connections to SSL sites without certificates
    • Optional flags:
      • --username, -u
      • --password, -p
    apimcli export-api -n PizzaShackAPI -v 1.0.0 -r chris@test.com -e dev -u chris@test.com -p chris123 -k
    Sample Response
    Succesfully exported API!
    Find the exported API at /Users/kim/.wso2apimcli/exported/apis/dev/PizzaShackAPI_1.0.0.zip
  • 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:

    The lifecycle status of the API is preserved when importing/exporting the API as the --preserveStatus flag is set to true by default.

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

    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
      • --environment, -e : The environment to which you what to import the API to.
      • --insecure, -k : This allows connections to SSL sites without certificates
      • --preserve-provider
    • Optional flags:
      • --username, -u
      • --password, -p
      • --preserveStatus : Preserves the lifecycle state of an API when importing/exporting. The default value is set to true. If this value is set to false the API will be exported in the CREATED status. 
        As the --preserveStatus is set to true by default the status of the API will be preserved when the API is exported. Therefore when the API is imported it will be imported to the new environment with the correct lifecycle state.
    apimcli import-api -f dev/PizzaShackAPI_1.0.0.zip -e production -u nick@example.com -p nick123 --preserve-provider=false -k
    ZipFilePath: /Users/kim/.wso2apimcli/exported/apis/dev/PizzaShackAPI_1.0.0.zip
    Successfully imported API 'dev/PizzaShackAPI_1.0.0.zip'
    Succesfully imported API!

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

List APIs

  1. Make sure that WSO2 API Manager is started and 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
    • --insecure, -k
  • Optional flags:
    • --username, -u
    • --password, -p

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

apimcli list apis -e dev -u admin -p admin -k
Environment: dev
No. of APIs: 2
+-------------------+---------+--------------+-----------+----------+--------------------------------------+
|       NAME        | VERSION |   CONTEXT    |  STATUS   | PROVIDER |                  ID                  |
+-------------------+---------+--------------+-----------+----------+--------------------------------------+
| PhoneVerification | 1.0.0   | /phoneverify | PUBLISHED | admin    | 2f25b332-4007-4c83-8249-b14b8af04848 |
| PizzaShackAPI     | 1.0.0   | /pizzashack  | PUBLISHED | admin    | 59e81b69-24d2-4fc4-9aaa-40665e119261 |
+-------------------+---------+--------------+-----------+----------+--------------------------------------+


Reset user

  1. Make sure that WSO2 API Manager is started and 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
    apimcli reset-user -e dev
    Successfully cleared user data for environment: dev

Check the version of the CLI

  1. Make sure that WSO2 API Manager is started and 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 WSO2 API Manager is started and 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 TLS renegotiation mode

By default, TLS renegotiation is disabled for the CLI tool. However, the TLS renegotiation mode can be configured by running the following command, which will be applied globally to all subsequent TLS connections established by the CLI.

apimcli set --tls_renegotiation_mode <never|once|freely>

Flags:

  • --tls_renegotiation_mode

Allowed values for this flag are,

never: Disable TLS renegotiation

once: Allow TLS renegotiation once

freely: Allow unrestricted TLS renegotiation

apimcli set --tls_renegotiation_mode freely


Set export directory

  1. Make sure that WSO2 API Manager is started and that the CLI import/export tool is running. 
  2. Run the following CLI command to 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.

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


  • No labels