[Article] Architecting a Multi-Environment API Manager Deployment with WSO2 API Manager

Table of contents

• Applies to
• Introduction
• Managing a multi-environment deployment
• How does WSO2 API manager handle artifact migration?
• API migration process
• Summary
• References

Applies to

Introduction

Many organizations embarking on the journey of APIs would eventually need to use an API management solution to manage these APIs. In most cases this API journey starts as a pilot project and strict organizational processes and practices adopted in areas of software development is not included in such pilot projects. More often than not these API initiatives become successful and creates the need to ensure the API management practice also falls in line with the organization’s processes and practices. One such example would be the use of isolated environments for development, QA, and production with strict controls on artifact access and modification. This article will focus on how WSO2 API Manager can be deployed in a multi-environment setup and how API artifacts can be managed and migrated between environments while adhering to standard processes and practices that are practiced in the software development space.

Managing a multi-environment deployment

A typical organization would maintain environments for development, QA, and production which would run autonomous and stakeholders of each environment would only have access to their own environment. Given the autonomous nature, each environment would act independent to each other; these environments may even have their own lifecycles to manage a process.

When this principle of isolated environments is applied to API management each environment would have its own deployment and its own API traffic that would be handled locally. APIs are created in the development environment, tested in the QA environment, and promoted to production to make it available for live traffic. In such a process, API artifacts will only be allowed to be created or modified in the development environment and only the artifacts that are thoroughly tested in the QA environment would be promoted to production.

In many organizations this responsibility of artifact migration lies with the devops team, who inevitably have access to and control of source and destination environments. To support this process, the product should allow a mechanism where its artifacts can be bundled and migrated with minimum intervention. Ideally, the devops engineer doesn’t need to be familiar with any user-interfaces or operations of the product, but should be able to do the migration via a command line interface that can either be scripted or manually executed.

Similarly, artifacts shouldn’t contain any environment-specific values that make the artifact obsolete when moved across environments. The ideal devops practice wouldn’t allow any modification to the artifacts and it should work as it is when migrated to the new environment. A common way to avoid this is by defining these environment-specific values as environment variables that can be referred to by the product when required. This way the artifacts would be portable and can be transferred to any environment without the need for any post migration changes.

How does WSO2 API manager handle artifact migration?

Most WSO2 products provide a Carbon Archive (.car) based artifact bundling mechanism, which when used with WSO2 Governance Registry, can provide a standardized way to migrate artifacts between autonomous environments. Carbon Archive based artifact bundling mechanism only works for artifacts that reside in the file system, hence this mechanism doesn’t work for WSO2 API Manager artifacts as API information is stored both in the file system as well as in the database. To facilitate bundling of APIs in WSO2 API Manager, a separate API Import/Export capability has been introduced to the WSO2 API Manager. This API Import/Export feature is not bundled with the product distribution, but needs to be deployed as a separate web application to the WSO2 API manager.

The API Import/export web application allows APIs to be exported and imported via a RESTful API. This would allow a user who doesn’t require any knowledge on the API manager to export and import APIs as required. The API Import/Export capability is secured via basic authentication and would require admin or equivalent credentials to import/export the APIs.

In order to make APIs totally portable, it should be able store environment specific values in the API as variables that can be referred to from the environment on which it is deployed. Backend service endpoint is the most common environment-specific value that is used in an API. This value is a critical parameter for an API and would need to refer to different backend services based on the environment on which it is deployed. As depicted in figure 1 below, an API deployed in the QA environment should point to services in the QA while the same API when deployed in the production environment should point to the production services.

Figure 1

WSO2 API Manager allows the capability to include variables in the API definition that can be mapped by the API Manager to system properties at service runtime. These properties can be given inline as command line arguments at the server startup or can be added to the server startup script.

API migration process

The API migration process can be depicted by figure 2 below.

Figure 2

In this example, let’s assume that we have two environments Dev/QA and Production. All artifacts that are deployed to production environment need to be tested in Dev/QA. No developer or a QA engineer is allowed to make any changes to the artifacts in the production environment and only the devops engineers are allowed to access the production environment.

The process starts when the API creator would create the required APIs in the Dev/QA environment. When creating APIs the API creator would use variables to represent environment-specific values, such as the endpoint hostname. As shown in figure 3 below, the hostname would be resolved by the API manager based on the environment on which it is deployed.

Figure 3

Once APIs are tested and verified the devops engineer would export the APIs using the API export capability of the API manager. The exported APIs can now be imported to the production environment. This would be done by the devops engineer through the available REST API. After importing the APIs to the production environment, a production administrator would log into the API Publisher dashboard and publish these APIs to the API Gateway of the production environment. The migrated APIs would now be available for traffic in the production environment.

Given below are the steps required to configure the environments to support multi-environment artifact migration.

1. Let’s start by deploying the API Import/Export web app in the two environments. This web app needs to be deployed in the publisher components of the API manager. The publisher component, in most cases, is deployed in the LAN which ensures that only internal users can make use of the API Import/Export feature. You can download the web app from the following URL¹. Deployment instructions are also available in the above URL.
2. Let’s now set the system variables for each environment. In this case, we assume that each environment has its own host name. You can provide the hostname as a command line argument at the server startup. This can be done by giving it an inline command when starting the server or you can modify the wso2server.sh/.bat file to add these arguments. Since this setup is done on Windows we will modify the wso2server.bat file in the Dev/QA environment by adding the following argument -Denvironment.host=qa.wso2.com to the list of CMD_LINE_ARGS. In the same way we will add -Denvironment.host=prod.wso2.com to the API Manager Startup script in the production environment.
3. There needs to be a mechanism for the API definition to pick these system variables. This can be done via a class mediator. Let’s add the env-resolver-1.0.0.jar (attached in the article) file to following location <API-M_HOME>/repository/components/lib. The source code for the above jar file can be found here³. The above Jar file can pick both the hostname and port from the system properties; however, we will only be using the hostname as a system variable.
4. Once the above jar file is added let’s create a sequence that would refer to this jar file. Add the following sequence as a global in sequence. Instructions on adding a global sequence can be found in the following link⁴.
   

   <sequence xmlns="http://ws.apache.org/ns/synapse" name="WSO2AM--Ext--In">
   	<class name="org.wso2.carbon.env.EnvironmentResolver"/>
   </sequence>
   

5. Let’s create APIs in the Dev/QA environment. When creating APIs make sure to put the hostname of the backend service as a variable (for example https://{uri.var.host}/sample/student).
6. Once all APIs have been created let’s export the APIs from the API manager in Dev/QA environment. Information on how to export APIs can be found in the following URL¹. The API export feature allows only a single API to be exported at once. The following tool⁵ allows you to perform bulk export of APIs from a given environment. This tool comes in handy if you have 100s of APIs that need to be migrated between environments. The source code and how to use this tool can be found in the following Github⁵ location.
7. You would now have zip archives of all the APIs that are exported. Let’s now import the APIs to your production environment.
8. Importing of APIs can be done by executing the API import REST Service. Given below is the corresponding curl command that can invoke the API import service.
   

   curl -H "Authorization:Basic <Base 64 encoded username:password>" -F file=@"<FilePath>\<Your API>.zip" -k -X POST "https://<Host:Port>/api-import-export-<Version>/import-api"
   

   Similar to Bulk API export, a tool is available for bulk importing of APIs where it is possible to import more than one API at once to WSO2 API Manager. The source code and how to use this tool can be found in the following Github⁶location

Summary

Adhering to standard software lifecycle process is important to move an API strategy from a mere pilot project to a full blown deployment. This article looked at how WSO2 API Manager can be configured to support a proper artifact migration process between different environments within the organization.

References

• [1] https://docs.wso2.com/display/AM1100/Migrating+the+APIs+to+a+Different+Environment
• [2] https://nuwanzone.blogspot.com/2015/03/api-gateways-with-dedicated-back-ends.html
• [3] https://drive.google.com/file/d/0B0sGgwec1rtXcW52RDNfV2E4TzQ/view
• [4] https://docs.wso2.com/display/AM1100/Adding+Mediation+Extensions
• [5] https://github.com/nadeesha5814/APIBulkExport
• [6] https://github.com/nadeesha5814/APIBulkImport