Migrating the APIs to a Different Environment
If you maintain multiple environments of the same API Manager version and you want to move all created APIs from one environment to another (such as moving from a development environment to a QA environment or from a QA environment to a production environment), you can migrate the APIs to the new environment by following the steps below:
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.
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 <API-M_HOME>/repository/conf/user-mgt.xml
. 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:
Sub directory/File | Description |
---|---|
Meta Information |
|
Documents |
|
Image | Thumbnail image of the API |
WSDL | WSDL file of the API |
Sequences | The sequences available for the API |
Given below is the RESTful API for the export functionality. It is secured using Basic Authentication.
Parameter | Description |
---|---|
URI |
|
Query parameters |
|
HTTP method | GET |
Examples | curl -H "Authorization:Basic YWRtaW46YWRtaW4=" -X GET "https://localhost:9443/api-import-export-2.1.0-v11/export-api?name=test&version=1.0.0&provider=admin" It gives a data stream as the output. To download it as a zipped archive, use the following command: curl -H "Authorization:Basic YWRtaW46YWRtaW4=" -X GET "https://localhost:9443/api-import-export-2.1.0-v11/export-api?name=test&version=1.0.0&provider=admin" -k > exportedApi.zip To verify the output status of the API call: curl -v -H "Authorization:Basic YWRtaW46YWRtaW4=" -X GET "https://localhost:9443/api-import-export-2.1.0-v11/export-api?name=test&version=1.0.0&provider=admin" -k > exportedApi.zip |
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
preserveProvider
parameter to true to keep it. If you set it to false, the original provider is replaced by the user who is sending the cURL command. - Once the APIs are imported, in order to make a particular version of an API the default in a group of different versions, select the
Make this the Default Version
checkbox before publishing the API. - 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 valve of the
preserveProvider
parameter must always be false.
Parameter | Description |
---|---|
URI |
|
Query parameters |
|
HTTP method | POST |
Example | Imports the API with the original provider preserved: Imports the API with the provider set to the current user: |
Deploying the API import/export tool
Download WSO2 API Manager 2.1.0 from http://wso2.com/products/api-manager/.
Download the latest WSO2 API import/export tool (
api-import-export-2.1.0-v11.war
) from here.Note that the import/export tool attached is specific to this version of WSO2 API Manager.
Copy the downloaded
api-import-export-2.1.0-v11.war
file to the<API-M_HOME>/repository/deployment/server/webapps
folder.Start the API Manager. If the server is already started, the file is automatically deployed as hot deployment is enabled.
Exporting an API
After successfully deploying the import/export tool, you can export an existing API as a .zip
archive. Issue the following cURL command using the command line:
curl -H "Authorization:Basic <base64-encoded-credentials-separated-by-a-colon>" -X GET "https://<APIM_HOST:Port>/api-import-export-<product-version>-<tool-version>/export-api?name=<API-name>&version=<API-version>&provider=<API-provider>" -k > <exportedApiName>.zip
To obtain <base64-encoded-credentials-separated-by-a-colon> use a base64 encoder (e.g., https://www.base64encode.org/) to encode your username and password using the following format: <username>:<password>
Thereafter, enter the encoded value for this parameter.
Here's an example:
curl -H "Authorization:Basic AbCdEfG" -X GET "https://localhost:9443/api-import-export-2.1.0-v11/export-api?name=PizzaShackAPI&version=1.0.0&provider=admin" -k > myExportedAPI.zip
Importing an API
You can use the archive created in the previous section to import APIs to an API Manager instance.
Make sure that API Manager is started and the import/export tool is deployed.
For Secure Endpoint Enabled APIs:
If you have enabled secure endpoints when creating the API, please follow the steps below before importing the API.
1. Unzip the .zip archive created in the previous section.
2. Go to PizzaShackAPI-1.0.0/Meta-information and open the
api.json
file.3. Modify the "endpointUTPassword" with your endpoint password and save the api.json file.
4. Compress the PizzaShackAPI-1.0.0 folder to a folder named myExportedAPI
Run the following cURL command:
curl -H "Authorization:Basic <base64-encoded-username-and-password-separated-by-a-colon>" -F file=@"full/path/to/the/zip/file" -k -X POST "https://<APIManagerHost:Port>/api-import-export-<product-version>-<tool-version>/import-api"
Here's an example:
curl -H "Authorization:Basic AbCdEfG" -F file=@"/Desktop/MyAPIFolder/myExportedAPI.zip" -k -X POST "https://localhost:9443/api-import-export-2.1.0-v11/import-api"
You must add a parameter named
preserveProvider
to the curl 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 cURL command. Here's an example:curl -H "Authorization:Basic AbCdEfG" -F file=@"/Desktop/MyAPIFolder/myExportedAPI.zip" -k -X POST "https://localhost:9443/api-import-export-2.1.0-v11/import-api?preserveProvider=false"
The preserveProvider parameter 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 preserveProvider 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 preserveProvider is set to false, when importing that API created by user-1to 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.1.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.1.0, backup and delete the
<API-M_2.1.0_HOME>
/solr
directory.
For more information, see Upgrading the API Manager to 2.1.0.
If the information about the user is stored in the userstore, you need to encode the username:password
combination before using it in the curl command.
If the information about the user is stored in the secondary userstore, encode the username and password as shown below.
user_domain/username:password
API import/export in a tenanted environment
To export an API from a tenant, follow the steps in Export an API. Use the tenant-specific encoded credentials in the cURL command. Here's an example:
curl -H "Authorization:Basic AbCdEfG" -X GET "https://<host>:port/api-import-export-2.1.0-v11/export-api?name=sample&version=1.0.0&provider=user@domain.com" -k > exportedApiName.zip
To import the API in another tenant, follow the steps in Importing an API. Use the encoded credentials for this tenant in the curl command. Here's an example:
curl -H "Authorization:Basic AbCdEfG" -F file=@"/home/user/Desktop/exportedApiName.zip" -k -X POST "https://<host>:port/api-import-export-2.1.0-v11/import-api?preserveProvider=false"
Note that the
preserveProvider
parameter value should be set tofalse
.