WSO2TORIAL: Migrating the APIs to a Different Environment

Posted by Daniel Stevanović on 11 Sep, 2015

In this episode of our WSO2 tutorialWith 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:

Parameter

Description

URI

https://<host name>:9443/api-import-export/export-api

Query parameters

name=<api_name>&version=<api_version>&provider=<provider_name>

Authorization header

Authorization:Basic <base64-encoded (username:password)>

HTTP method

GET

 

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:

 

11_sep_no_1.jpg

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:

Parameter

Description

URI

https://<host name>:9443/api-import-export/import-api

Query parameters

preserveProvider=<true|false>

Authorization header

Authorization:Basic <base64-encoded (username:password)>

HTTP method

POST

 

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

 

Check our webinars

Topics: WSO2, WSO2 API

Written by Daniel Stevanović

Daniel Stevanović
Daniel is an integration consultant at Yenlo with over 7 years of experience in software development, middleware and service-oriented architecture (SOA) with knowledge of e.g. Java, JavaEE, Spring, OAuth. He is working on several middleware integration projects using the WSO2 product stack.