This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.
Working with the Microgateway in a Windows Environment
This documentation is for the API Microgateway component that is coupled with WSO2 API Manager 2.6.0.
View the documentation for the latest release - WSO2 API Microgateway 3.0.2.
You can work with the WSO2 API Manager Microgateway in a Microsoft Windows environment as follows:
Before you begin
Make sure to have the following prerequisites in place to initialize a Microgateway instance,
- Oracle Java 1.8
- WSO2 API Manager (WSO2 API-M) 2.5.0 or later.
This is required to bootstrap the Microgateway. - WSO2 Microgateway CLI tool
- NSSM (the Non-Sucking Service Manager)
This is required if you need to run the Microgateway as a Windows service.
Running the Microgateway on a Windows operation system
Follow the steps below run a WSO2 API Manager Microgateway instance in a Windows environment.
Step 1 - Set up JAVA_HOME
You need to set up JAVA_HOME
in order to run the Microgateway CLI tool.
- Install the Oracle Java 1.8 or higher version.
- Set the
JAVA_HOME
environment variable as a user variable via the edit system properties UI.
Step 2 - Set up a Microgateway project
- Start the WSO2 API Manager server.
- Create a new API in the API Publisher and publish it.
If you have not created any APIs so far, you can deploy the sample Pizzashack API. Create a Microgateway label to assign it to the newly created API.
For more information, see Generating a Microgateway distribution for a label.It is not mandatory to create a Microgateway label because you can deploy a Microgateway in either one of the following instances based on your requirement.
- Deploy a Microgateway for an API in order to deploy it for a single API.
- Deploy a Microgateway for a Microgateway label in order to deploy the Microgateway for a group of APIs.
- Set up the Microgateway CLI tool.
Add the Microgateway executable location to the path variable.- Download the Microgateway (
wso2am-micro-gw-toolkit-x.x.x.zip
). - Unzip the downloaded ZIP file to a location of your choice (e.g.,
C:\Program Files\wso2\micro gateway cli\
). - Copy the path to the Microgateway
bin
folder (<path-to-wso2am-micro-gw-toolkit>\bin
). - Click Edit the system preferences.
- Navigate to the Advanced tab and click Environment Variables.
- Navigate to the path system variable and click Edit.
Click New, add the path to the Microgateway
bin
folder that you copied previously and click OK three times to save the newly added system variable.
As you have added the Microgateway
\bin
directory path to the system variables, you can invoke the Microgateway command from any directory in the system.
- Download the Microgateway (
- Initialize the Microgateway project.
- Open the Microsoft command line (
cmd.exe
). Change the location to where you want to set up the Microgateway project.
cd <directory-location-to-set-up-microgateway-project>
Run the following command to bootstrap a Microgateway instance.
In this guide, as we have assigned a label to the API, you only need to run the first command.If you want to set up a Microgateway for a Microgateway label, use the following command.
micro-gw setup <project-name> -l <label-name>
If you want to set up a Microgateway project for a single API, use the following command.
micro-gw setup <project-name> -a <API-name> -v <API-version>
This will create a project for that particular API name and version.
The remainder of the process is the same for a label-based project and a private jet API project.
Enter your username and password when prompted.
If you have run the Microgateway CLI tool before, you are not prompted to enter your username again unless you have reset the Microgateway CLI tool.
Press Enter for all the other questions when prompted so that it picks up the default values.
If you have run the Microgateway CLI tool before, you are not prompted to enter the following details unless you have reset the Microgateway CLI tool.
After this process is complete, a directory is created with the given project name. The structure of the project is similar to the following:
- Open the Microsoft command line (
Step 3 - Build the Microgateway
Navigate to the Microgateway project root directory.
If you have not changed the directory after step 5 when setting up the Microgateway project, this is the same directory where you ran the set up command.Run the following command to build the project.
Use the same project name that you defined when setting up the Microgateway project.micro-gw build <project-name>
After running the build command, you can find the Microgateway distribution (
micro-gw-<project-name>.zip
) specifically designed for the given Microgateway label or the respective API version in the<project-name>\target
directory.
Step 4 - Run the Microgateway
- Copy the <
micro-gw-project-name>.zip
file from the<project-name>\target
directory and extract the files to where you want to run the Microgateway. Navigate to the <
micro-gw-project-name>/bin
directory.cd <micro-gw-project-name>/bin
Run the Microgateway.
This runs the Microgateway instance in the foreground..\gateway.bat
Run the Microgateway as a Windows service
Step 1 - Set up JAVA_HOME
You need to set up Java in order to run the Microgateway CLI tool.
- Install Oracle Java 1.8 or later.
- Set the
JAVA_HOME
environment variable as a server variable via the edit system properties UI.
Step 2 - Set up a Microgateway project
- Start the WSO2 API Manager server.
- Create a new API in the API Publisher and publish it.
If you have not created any APIs so far, you can deploy the sample Pizzashack API. Create a Microgateway label to assign it to the newly created API.
For more information, see Generating a Microgateway distribution for a label.It is not mandatory to create a Microgateway label because you can deploy a Microgateway in either one of the following instances based on your requirement.
- Deploy a Microgateway for an API in order to deploy it for a single API.
- Deploy a Microgateway for a Microgateway label in order to deploy the Microgateway for a group of APIs.
- Set up the Microgateway CLI tool.
Add the Microgateway executable location to the path variable.- Download the Microgateway (
wso2am-micro-gw-toolkit-x.x.x.zip
). - Unzip the downloaded ZIP file to a location of your choice (e.g.,
C:\Program Files\wso2\micro gateway cli\
). - Copy the path to the Microgateway
bin
folder (<path-to-wso2am-micro-gw-toolkit>\bin
). - Click Edit the system preferences.
- Navigate to the Advanced tab and click Environment Variables.
- Navigate to the path system variable and click Edit.
Click New, add the path to the Microgateway
bin
folder that you copied previously and click OK three times to save the newly added system variable.
As you have added the Microgateway
\bin
directory path to the system variables, you can invoke the Microgateway command from any directory in the system.
- Download the Microgateway (
- Initialize the Microgateway project.
- Open the Microsoft command line (
cmd.exe
). Change the location to where you want to set up the Microgateway project.
cd <directory-location-to-set-up-microgateway-project>
Run the following command to bootstrap a Microgateway instance.
In this guide, as we have assigned a label to the API, you only need to run the first command.If you want to set up a Microgateway for a Microgateway label, use the following command.
micro-gw setup <project-name> -l <label-name>
If you want to set up a Microgateway project for a single API, use the following command.
micro-gw setup <project-name> -a <API-name> -v <API-version>
This will create a project for that particular API name and version.
The remainder of the process is the same for a label-based project and a private jet API project.
Enter your username and password when prompted.
If you have run the Microgateway CLI tool before, you are not prompted to enter your username again unless you have reset the Microgateway CLI tool.
Press Enter for all the other questions when prompted so that it picks up the default values.
If you have run the Microgateway CLI tool before, you are not prompted to enter the following details unless you have reset the Microgateway CLI tool.
After this process is complete, a directory is created with the given project name. The structure of the project is similar to the following:
- Open the Microsoft command line (
Step 3 - Build the Microgateway
Navigate to the Microgateway project root directory.
If you have not changed the directory after step 5 when setting up the Microgateway project, this is the same directory where you ran the set up command.Run the following command to build the project.
Use the same project name that you defined when setting up the Microgateway project.micro-gw build <project-name>
After running the build command, you can find the Microgateway distribution (
micro-gw-<project-name>.zip
) specifically designed for the given Microgateway label or the respective API version in the<project-name>\target
directory.
Step 4 - Install the Gateway script as a Windows service
- Download the NSSM (Non-Sucking Service Manager) tool and extract the ZIP file.
- Copy the extracted ZIP file to the location where you want to run the Microgateway.
- Install the
gateway.bat
script as a Windows service.Navigate to the
win64
folder, which is inside the new location of the extracted NSSM tool.cd apim_2_5_microgateway_bat\nssm-2.24\win64
Run the following command to install the
gateway.bat
script as a Windows service.nssm.exe install microgw
- Click Yes when the following User Account Control message appears.
You need to do this in order to allow the NSSM tool to make changes to your Microgateway distribution.
- Click [...] and select the location of the
gateway.bat
file, which is in the\bin
folder of your unzipped Microgateway distribution.
- Click Details, and enter the details of the Microgateway service.
- Click Install service.
A confirmation message appears.
Testing the Microgateway
You can invoke the API through the Microgateway using the following cURL command in order to test the Microgateway. By default, the Microgateway serves the HTTPS/WSS request via the 9095 port.
Resetting the Microgateway CLI tool
When you run the Microgateway CLI tool for the first time, it preserves all the information (i.e., your username, APIM base URL, TrustStore location and the TrustStore password) with the exception of your password, for later use. If you want to reset the Microgateway CLI tool in order to clear all the data that has been preserved by the Microgateway CLI tool, you can use the –reset
argument as follows. Note that you can invoke the Microgateway CLI tool reset command from any directory in the system.
micro-gw reset