WSO2TORIAL: Migrating the APIs to a Different Environment

In this episode of our WSO2 tutorial: With the introduction of the WSO2 API Manager 1.9.0 it is now possible to copy APIs from one server environment to another, so that you do not have to create them again in the new environment. WSO2 provides RESTful API which can be used to export/import all registry resources and meta information for requested API.

API import/export tool is not yet included in the official binary release therefore you need to download it manually from here.

Deploying the API import/export tool

1. Download WSO2 API import/export tool
2. Copy the downloaded WAR file to <APIM_HOME>/repository/deployment/server/webapps
3. Start the API Manager. If the server is already started, the file will be automatically deployed as hot deployment is enabled.

How it works
The API import/export tool uses a RESTful API, protected by basic authentication. Only users with admin privileges are allowed to access it. 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 WAR file as a Web application to the server.

Export/import API

Export API:

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:

Meta Information

• api.json: contains all the basic information required for an API to be imported in another environment
• swagger.json: contains the API swagger definition

Documents

• docs.json: contains the summary of all the documents available for the API
• Add the uploaded files for API documentation also

Image

Thumbnail image of the API

WSDL

WSDL file of the API

Sequences

The sequences available for the API

Import 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 resources exported from the source environment.

Notes:

• 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 will not be added to the new environment. However, if an exported sequence is not available it will be added.
• The importer can decide whether to keep the original provider’s name or replace it. Set thepreserveProvider parameter to true to keep it. If you set it to false, the original provider will be replaced by the user who is invoking the import.
• Cross-tenant imports are not allowed while preserving the original provider. For example, if an API is exported from tenant A and imported to tenant B, the value of the preserveProviderparameter must always be set to false.

Examples

Exporting an API

1. Start the API Manager, go to publisher, login as admin and deploy sample API
2. Run the following cURL command:
   curl -H "Authorization:Basic YWRtaW46YWRtaW4" -X GET "https://localhost:9443/api-import-export/export-api?name=WeatherAPI&version=1.0.0&provider=admin" -k > exportedWeatherAPI.zip
3. You can find exportedWeatherAPI.zip in your current directory

Note: If you are exporting with a tenant set provider value as
provider=admin@<tenant_domain>

Importing an API

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

1. Make sure the API Manager is started and the import/export tool is deployed. 
2. Run the following cURL command:
   curl -H "Authorization:Basic YWRtaW46YWRtaW4=" -F file=@"exportedWeatherAPI.zip " -k -X POST "https://localhost:9443/api-import-export/import-api"

Note: If you want to override provider for imported API add “?preserveProvider=false” to the command above. When you are importing API across different tenants you must add this.

Known bugs/limitations

1. If you try to use import/export tool version 0.9.1, which is currently referenced in API Manager documentation here, on operating systems that use different path separators (e.g. exporting from Windows and importing on Linux) it will fail because it will not be able to extract ZIP archive.You can checkout version for API Manager 1.9.1 from https://github.com/wso2/product-apim/tree/v1.9.1/modules/api-import-export where this bug has been fixed and build WAR from sources using Maven.
2. If you have different gateway environments configured on the API Manager that you are importing API to, they will not be configured by default. Instead, you will have to manually edit API definition after import and select them in order to be able to publish your API. If you are importing multiple APIs (or you want to automate this) it can be very time consuming.
   To resolve this, you can download our version of the import/export tool from here which supports additional query parameter preserveGateway (this version also incorporates bug fix for previously mentioned problem with path separators). If you set its value to false (addpreserveGateway=false) all available gateways on target environment will be automatically configured after import and you can just publish your API afterwards.

Please consult the documentation for more information on migrating API’s at https://docs.wso2.com/display/AM190/Migrating+the+APIs+to+a+Different+Environment

WSO2TORIALS help you to change, update or improve WSO2 products and are based on our experiences with the products. WSO2TORIALS will guide you step by step with minimal knowledge required.