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

All docs This doc

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Warning

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.

Table of Contents
maxLevel3
minLevel3

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.

Multiexcerpt
hiddentrue
MultiExcerptNamenote1

NOTE TO WRITERS:

Do not attach the api-import-export-2.6.0.war file to this page. Instead, attach it to (1) and add that link here.

(1) https://docs.wso2.com/display/attachments/API+Manager+2.6.0

Multiexcerpt include
SpaceWithExcerptAM260
MultiExcerptNameCLI_tool
PageWithExcerptMigrating the APIs and Applications to a Different Environment

Migrating APIs to different environments

Table of Content Zone
locationtop

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.
Localtab Group
Localtab
activetrue
idFormat-exportAPI
titleCommand 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
    • --environment, -e
    • --insecure, -k : This allows connections to SSL sites without certificates
Localtab
idExample-exportAPI
titleExample
Code Block
apimcli export-api -n PhoneVerification -v 1.0.0 -r admin -e dev -k
Localtab
idReponse-exportAPI
titleResponse
Code Block
Succesfully exported API!
Find the exported API at /Users/kim/.wso2apimcli/exported/apis/dev/PhoneVerification_1.0.0.zip

Importing an API

Multiexcerpt
MultiExcerptNameimportAPIcreated
Note

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. 

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

    Localtab Group
    Localtab
    activetrue
    idFormat-importAPI
    titleCommand Format
    Code Block
    apimcli import-api -f <environment>/<file> -e <environment> -k
    Code Block
    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.
    Localtab
    idExample-importAPI
    titleExample
    Code Block
    apimcli import-api -f dev/PhoneVerification_1.0.0.zip -e production -u admin -p admin -k
    Localtab
    idResponseImport
    titleResponse
    Code Block
    titleSample 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!
    Tip

    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:

    Localtab Group
    Localtab
    activetrue
    idFormat-preserve
    titleCommand Format
    Code Block
    apimcli import-api -k -f <environment>/<file> -e <environment> -u <username> -p <password> --preserve-provider <preserve_provider>
    Code Block
    apimcli import-api --insecure --file <environment>/<file> --environment <environment> -u <username> -p <password> --preserve-provider=<preserve_provider>
    Note

    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
    Localtab
    idExample-preserve
    titleExample
    Code Block
    apimcli import-api -k -f dev/PhoneVerification_1.0.0.zip -e production -u admin -p admin --preserve-provider=false
    Note

    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.

    Info
    titleTroubleshooting

    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

Note

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: 

    Localtab Group
    Localtab
    activetrue
    idFormat-exportAPITenant
    titleCommand Format
    Code Block
    apimcli export-api -n <API-name> -v <version> -r <provider> -e <environment> -u <username> -p <password> -k
    Code Block
    apimcli export-api --name <API-name> -version <version> --provider <provider> --environment <environment> --username <username> --password <password> --insecure
    Note

    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
    Localtab
    idExample-exportAPITenant
    titleExample
    Code Block
    apimcli export-api -n PizzaShackAPI -v 1.0.0 -r [email protected] -e dev -u [email protected] -p chris123 -k
    Localtab
    idResponseExportAPITenant
    titleResponse
    Code Block
    titleSample 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:

    Multiexcerpt include
    SpaceWithExcerptAM260
    MultiExcerptNameimportAPIcreated
    PageWithExcerptMigrating the APIs to a Different Environment

    Localtab Group
    Localtab
    activetrue
    idFormatImportAPI
    titleCommand Format
    Code Block
    apimcli import-api -f <environment>/<file> -e <environment> -u <username> -p <password> --preserve-provider <preserve_provider>
    Code Block
    apimcli import-api --file <environment>/<file> --environment <environment> --username <username> --password <password> --preserve-provider <preserve_provider>
    Note

    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.
    Localtab
    idExampleImportAPI
    titleExample
    Code Block
    apimcli import-api -f dev/PizzaShackAPI_1.0.0.zip -e production -u [email protected] -p nick123 --preserve-provider=false -k
    Localtab
    idResponseImportAPITenant
    titleResponse
    Code Block
    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.
Localtab Group
Localtab
activetrue
idFormatListAPI
titleCommand Format
Code Block
apimcli list apis -e <environment> -u <username> -p <password> -k            
Code Block
apimcli list apis --environment <environment> --username <username> --password <password> --insecure
Code Block
apimcli list apis --environment <environment> --limit <maximum number of APIs> --insecure

Flags:

  • Required flags:
    • --environment, -e
    • --insecure, -k
  • Optional flags:
    • --username, -u
    • --password, -p

    • --limit, -l : Maximum number of APIs to return 

      Note
      The username and password are optional flags. You will be prompted to enter your credentials if you do not provide these flags.
Localtab
idExample-listAPI
titleExample
Code Block
apimcli list apis -e dev -u admin -p admin -k
Code Block
apimcli list apis --environment dev --username admin --password admin --insecure
Code Block
apimcli list apis --environment dev --limit 40 --insecure
Localtab
idResponse-listAPI
titleResponse
Code Block
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 |
+-------------------+---------+--------------+-----------+----------+--------------------------------------+
Multiexcerpt
hiddentrue
MultiExcerptNameMigrating Applications

Migrating applications to different environments

Table of Content Zone
locationtop

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.

  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 application as a .zip archive.
Localtab Group
Localtab
activetrue
idFormat-exportApp
titleCommand Format
Code Block
apimcli export-app -n <application-name> -o <owner> -e <environment> -u <username> -p <password> -k
Code Block
apimcli export-app --name <application-name> --owner <owner> --environment <environment> --username <username> --password <password> --insecure
Note

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
    • --environment, -e : The environment to which you what to export the application to.
    • --insecure, -k : This allows connections to SSL sites without certificates
  • Optional flags:
    • --username, -u
    • --password, -p
Localtab
idExample-exportapp
titleExample
Code Block
apimcli export-app -n SampleApp -o admin -e dev -u admin -p admin -k
Localtab
idResponse-exportapp
titleResponse
Code Block
Succesfully exported Application!
Find the exported Application at /Users/kim/.wso2apimcli/exported/apps/dev/admin_SampleApp.zip

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.

  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 import an existing application as a .zip archive.
Localtab Group
Localtab
activetrue
idFormat-importApp
titleCommand 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
Note

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/dev/admin_SampleApp.zip , then you need to enter dev/admin_SampleApp.zip as the value for this flag.
    • --environment, -e : The environment to which you what to import the application to.
    • --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, from the previous environment. 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
idExample-importapp
titleExample
Code Block
apimcli import-app -f dev/admin_SampleApp.zip -e production -o admin --preserveOwner --skipSubscriptions -u admin -p admin -k
Localtab
idReponse-importapp
titleResponse
Code Block
ZipFilePath: /Users/kim/.wso2apimcli/exported/apps/dev/admin_SampleApp.zip
Completed importing the Application 'dev/admin_SampleApp.zip'
Succesfully imported Application!

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

  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 apps.
Localtab Group
Localtab
activetrue
idFormat-listApps
titleCommand Format
Code Block
apimcli list apps -e <environment> -u <username> -o <owner> -p <password> -k             
Code Block
apimcli list apps --environment <environment> --owner <owner> --username <username> --password <password> --insecure
Code Block
apimcli list apps --environment <environment> --limit <maximum number of applications> --insecure             

Flags:

  • Required flags
    • --environment, -e
    • --owner, -o
    • --insecure, -k : This allows connections to SSL sites without certificates
  • Optional flags
    • --username, -u
    • --password, -p
    • --limit, -l : Maximum number of Applications to return
Note

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

Localtab
idExample-listApps
titleExample
Code Block
apimcli list apps -e dev -o admin -u admin -p admin -k
Code Block
apimcli list apps --environment dev --username admin --password admin --insecure
Code Block
apimcli list apps --environment dev --limit 40 --insecure
Localtab
idResponse-listApps
titleResponse
Code Block
Environment: production
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

  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.

    Localtab Group
    Localtab
    activetrue
    idFormat-ResetUser
    titleCommand Format
    Code Block
    apimcli reset-user -e <environment>
    Code Block
    apimcli reset-user --environment <environment>

    Flags:

    • Required flags
      • --environment, -e
    Localtab
    idExample-ResetUser
    titleExample
    Code Block
    apimcli reset-user -e dev
    Localtab
    idResponseClearUser
    titleResponse
    Code Block
    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.

    Localtab Group
    Localtab
    activetrue
    idFormat-CLIver
    titleCommand
    Code Block
    apimcli version
    Localtab
    idExample-CLIver
    titleExample
    Code Block
    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.

    Localtab Group
    Localtab
    activetrue
    idFormat-RstTime
    titleCommand Format
    Code Block
    apimcli set --http-request-timeout <http-request-timeout>

    Flags:

    • --http-request-timeout

    Localtab
    idExample-RstTime
    titleExample
    Code Block
    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.

Localtab Group
Localtab
activetrue
idFormat-expDir
titleCommand Format
Code Block
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

Localtab
idExample-expDir
titleExample
Code Block
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.

    Localtab Group
    Localtab
    activetrue
    idFormat-expDir
    titleCommand Format
    Code Block
    apimcli set --export-directory <export-directory-path>

    Flags:

    • --export-directory

    Localtab
    idExample-expDir
    titleExample
    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.

Note

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. 

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

Note

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.

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