WSO2 is an open source application development software company focused on providing service-oriented architecture solutions for professional developers.

docker, microservices, api-gateway, gateway, apis, cloud-native, microgateway, ballerina-lang


WSO2 API Microgateway

The WSO2 API Microgateway (MGW) is a Cloud Native API Gateway which can be used to expose one or many microservices as APIs.

The WSO2 API Microgateway is designed to expose heterogeneous microservices as APIs to end consumers using a common API interface based on the Open API Specification. This helps expose microservices using a unified interface to external consumers, internal consumers and partners. It applies the common quality of service attributes on API requests such as security, rate limiting and analytics and also offers a wide range of features which helps organizations to deploy APIs microservice architectures efficiently.

Build Status License License CII Best Practices

Table of Contents

Quick Start

Let's expose the publicly available petstore service via microgateway.

  1. Download the latest WSO2 API Microgateway release from the product official page or github release page and extract it. For Docker container based usages, downloading only the toolkit will be sufficient.

  2. Add the 'bin' directory of the extracted distributions to your PATH variable.

    Virtual Machine
  3. First we need to initialize a project by adding the open API definition of the petstore service. We'll name the project as "petstore". To initialize the project, execute following command.

    micro-gw init petstore -a
  4. The project is now initialized with the open api definition of the petstore service.

  5. Next, Lets build the project and create a microgateway instance.

    micro-gw build petstore --docker-image petstore:v1 --docker-base-image wso2/wso2micro-gw:3.2.0
    Virtual Machine
    micro-gw build petstore
  6. Start the gateway.

    docker run -d -p 9090:9090 -p 9095:9095 petstore:v1
    Virtual Machine
    gateway <PROJECT_LOCATION>/target/petstore.jar
  7. Now we can test our API. Since APIs on the MGW are by default secured. We need a valid token or key in order to invoke the API. MGW can issue API keys on its own. Execute the command below to get a API key from microgateway. Following command will set the api key into TOKEN variable.

    TOKEN=$(curl -X get "https://localhost:9095/apikey" -H "Authorization:Basic YWRtaW46YWRtaW4=" -k)
  8. We can now invoke the API running on the microgateway using cURL as below.

    curl -X GET "https://localhost:9095/v2/pet/1" -H "accept: application/json" -H "api_key:$TOKEN" -k



Below is a list of most noticeable features out of many other features MGW hosts.

  1. Exposing one or more microservices as APIs using the Open API Specification.
  2. Authentication and Authorization based on OAuth2.0 (opaque tokens and JWTs), API keys, Basic Auth and Mutual TLS.
  3. Rate Limiting of API requests based on numerous policies.
  4. Business Insights through API Analytics.
  5. Service discovery.
  6. Request and Response transformations.
  7. Load balancing, failover and circuit breaking capabilities of API requests.
  8. Seamless Docker and Kubernetes integration.
  9. Integration with WSO2 API Manager to support design first APIs, API Analytics and shared rate limiting.

It also has the following characteristics that makes it a perfect fit for microservice architectures

  • Less than 1s startup time, allowing faster scaling.
  • Built on a stateless architecture, allowing for infinite scaling.
  • Has an immutable runtime, making it heavily robust.
  • CI/CD friendly worlkflow.
  • Runs in isolation with no dependencies to other components



Exposing APIs with MGW involves in two main phases.

Dev Phase

MGW uses OpenApi specification and a set of MGW specific OpenApi vendor extensions to define an API. Users can use these extensions to enable/disable different gateway features on an API. A sample can be found in here. Dev phase involves defining the required API(s) using these extensions. This phase can involve below basic steps.

  1. Initializing a project.
  2. Adding/updating project's OpenApi definition(s).
  3. Sharing the project with other developers/teams (in Github or any VCS)

Ops Phase

Once the project is ready for the deployment, MGW can produce three types of main deployment artifacts. Out of these three types, you can select which artifact(s) you need for the required deployment.

  1. Executable
    This is the default build output of a project. Output executable can be provided to a MGW runtime installation to start a microgateway server instance. Otherwise this executable can me mounted to a MGW docker container.
  2. Docker
    MGW Toolkit build command can be configured to produce a docker image required to create a docker installation.
  3. Kubernetes
    Similar to docker images, build command can be configured to produce kubernetes artifacts required to create a kubernetes installation.


MGW runtime is mostly implemented with ballerina-lang. However the toolkit is implemented with Java. You can contribute your code to both runtime and toolkit.

Contribution is not limited to the code. You can help the project with identifying issues, suggesting documentation changes etc.

For more information on how to contribute, read our contribution guidelines.