15 Jul, 2019 | 3 min read

WSO2 API Microgateway 3.0 is Released

  • Rajith Roshan
  • Associate Technical Lead - WSO2

The WSO2 API Manager team recently released version 3.0 of its WSO2 API Microgateway. This blog takes a closer look at the key attributes of a microgateway, changes in the new release, new features available, use cases of microgateway, and what to expect in the future from WSO2 API Microgateway.

Key Attributes

Cloud native

  • Comes as lightweight containers (fast boot-up times, low memory footprint, and low distribution size
  • Designed in a stateless manner
  • Isolated from underlying system/OS
  • Can be deployed on self-service, elastic, and cloud infrastructure
  • Agile DevOps and CI/CD
  • Automated capabilities for deployment
  • Developed with frameworks suited for cloud (based on Ballerina)

Developer-centric and enables the following:

  • Creation of microservices
  • Define the open API definition for microservices
  • Initiate the microgateway project from the open API definition
  • Build the microgateway project
  • Locally test the service exposed via microgateway


  • Decentralized per API gateway, with a dedicated gateway for each service
  • Contains a private jet gateway, with a dedicated gateway for clusters of same microservices
  • Contains sidecar gateways, gateways that are deployed in the same node with microservices
  • A gateway for subset of APIs only, to expose several services/APIs using a single API


  • Rebuild required if API changes, new resource added
  • Finalize open API definitions prior to deploying
  • Immutable containers
  • Immutable runtime artifacts for non containerized runtimes


  • Serves traffic independently (acts without key manager with self contained tokens, local rate limiting capabilities, and stores analytics data)
  • Independent scaling sans the need to scale other components
  • Can be scaled with microservices when used as private jet or side car mode
  • Inbuilt support for container orchestration tools to manage scaling

What Has Changed in the New Release?

1. Introduction of a developer-first approach

The 2.x series of WSO2 API Microgateway depended on the WSO2 API Manager publisher portal when designing APIs to be exposed via the microgateway. WSO2 API Microgateway 3.0 takes a developer-first approach. The API developer who is designing APIs and defining the interfaces of the APIs is now able to develop a microgateway based on the interface of his/her APIs.

In this new version, the microgateway toolkit will accept a valid open API definition of developer services or microservices, with WSO2 specific open API extensions. Then the toolkit will translate this open API definition into an executable format which is accepted by the microgateway runtime component. Once the API developer adds WSO2 specific open API extensions to the open API definition of the microservices, microgateway will add QoS like authentication, authorization, rate limiting, transformations, analytics, etc.

2. Separation of toolkit and runtime into two distributions

The 2.x series of WSO2 API Microgateway had a single distribution where both toolkit and runtime resided. The toolkit created runtime distribution for the user, containing all the APIs which the user had to add to the project. This has changed in WSO2 API Microgateway 3.0, which has two separate distributions, one for the toolkit and the other for the runtime. I've explained this in detail in the section below.

  • Microgateway toolkit

Microgateway toolkit is a command line tool designed for API developers to create micro gateway projects by adding open API definitions. This cli creates a project structure for the API developer once the project is initiated. If the API developer has a single open API definition or multiple open API definitions, these can be copied to this newly created project. Once the project is finalized, the cli can be used to build this project which will create an executable file that is accepted by the microgateway runtime.

  • Microgateway runtime

This is the component which actually serves the API requests. Runtime component cannot be run without providing the output created by the toolkit. The runtime component can be dowloaded as a zip file or as a docker image. When using a zip file, the executable file created by this toolkit should be provided as an input argument for the startup scripts of the runtime. When using the docker image, the executable file should be mounted into the docker container.

You can refer to the quick start guide to expose your first API with microgateway in a few steps here:

New Features

Define per resource endpoints

In the microservices world, developers might want to expose their microservices as APIs to the outside world. The API developer will define an interface of these services using open API definitions. Several microservices will be contained in a single open API definition which defines a single API for a particular use case (for example, online store). So when defining the microservices in the open API definition as REST resources, users should be able to define different back ends based on the resource.

Open API extension (“x-wso2-production-endpoints", “x-wso2-sandbox-endpoints”) introduced by WSO2 enables users to define back end services at the resource level. This way, users can logically collect his microservices into a single API and these can be exposed via the microgateway. Refer to the documentation here.

HTTP2 support

WSO2 API Microgateway is upgraded to support HTTP/2 together with HTTP/1.1 as the incoming and outgoing transport protocol. WSO2 API Microgateway is able to process requests faster and simpler with HTTP/2 enablement. For more information on HTTP/2 and its benefits, refer to the HTTP/2 homepage. It supports both client -> gateway and gateway -> back end communication using http2. Refer to the documentation here.

Mutual SSL based authentication

Microgateway is enabled to serve requests from trusted clients without providing OAuth2 tokens. After sharing the certificates of the trusted client partners are, requests from these trusted certificates will be served. Microgateway can impose the mutual ssl as required or as optional. If required, then requests from only trusted clients will be served, and if it is optional, the trusted client will be served without OAuth2 tokens and untrusted clients (the client who has not shared their public certificates) will need a valid OAuth2 token.

Config based basic authentication support

Microgateway allows users to invoke APIs using their basic authentication credentials, apart from OAuth2 tokens as well. The basic authentication support can be defined per API using the open API definition. Microgateway supports the open API security schemes in order to define the basic authentication for the APIs. Refer to the documentation here.

Response and request schema validation

Microgateway can intercept responses and requests, and validate these against the models defined in the open API definition. Microgateway stores the open API definitions added to the microgateway project and cross check the request and response payloads against the schema models defined in the open API definitions. Refer to the documentation here.

Service discovery with ETCD

One challenge we face with microservices architecture is that the services are dynamic. Services do not have a fixed connection url, it changes with time, and are mostly maintained in a ETCD server as a key value pair. Since microgateway is immutable, it should be able to route traffic to these dynamics endpoints without having to rebuild. Connecting with the ETCD server and resolving dynamic micro services urls in real time are both supported by the microgateway. Refer to the documentation here.

Global throttling

Up to date, the microgateway was able to perform the rate limiting locally using memory. Each gateway maintained its own set of counters and throttling decision were taken in an independent manner. With this new release, the microgateway enables the publication of throttle events to the WSO2 API Manager traffic manager component, and take decisions based on traffic manger subscriptions.

Integration with third party key managers

By default all the APIs in the microgateway are OAuth2 protected. Hence API consumers require a valid OAuth2 token in order to invoke the APIs. Microgateway supports self contained jwt OAuth2 access tokens from any trusted key manager. In order to validate the jwt token sent by the key manager, microgateway requires the public certificate of the key manager in its trust store.

Request and response transformations

Microgateway now has the first class support to plugin external functions written in Ballerina, as interceptors during the request in-flow and the response out-flow. API developers can manipulate request/response headers, body, etc. prior to sending to the back end or responding to the client.

API/Resource level throttling

Earlier versions of microgateway only supported application and subscription level throttling. With this new version onwards, API developers can define new policies in the policy.yaml file of their project and attach them to the APIs using the open API extensions.

JWT revocation

Microgateway self validates the jwt tokens issued by the trusted key manager. It validates the JWT tokens signature using the public certificate of the key manager which signed the JWT. Due to this self validation mechanism microgateway will accept revoked tokens until they are get expired. So there should be a mechanism to notify microgateway about revoked jwt tokens. There are two mechanisms supported by microgateway:

  • Persistant notification via ETCD server

Microgateway can connect an ETCD server during startup and fetch all revoked tokens from the ETCD server. In the key manager component which issues and revokes tokens, there should be an extension point to add the revoked token into an ETCD server. When revoked tokens are added with their validity period, the ETCD server automatically removes them upon the expiration, hence mitigating the aggregation of revoked tokens on the ETCD server.

  • Real time notification via JMS

Microgateway can be configured to subscribe to a JMS topic to fetch details about tokens that are revoked during the runtime. This way, microgateway is notified about the tokens that get revoked after the server startup. In the key manager component, there should be an extension point to add the revoked token to the JMS topic.

Microgateway Deployment Use Cases

1.Monolithic centralized deployments

2.Use in microservices architecture as a private jet or sidecar gateway

3.Exposure point for the microservices as APIs in service mesh

What to Expect in the Near Future

  • GRPC support
  • Observability with Prometheus and Grafana
  • Cookie based authentication for SPAs
  • CI/CD with APIM import export tool and publish to WSO2 API Manager
  • Improved toolkit to fetch open API definitions from any URL
  • K8s CRDs with enhanced dev focussed design

Learn more about WSO2 API Microgateway here.

We have also organized a webinar which will explore in detail the architectural changes, new features and use cases, deployment patterns, and demonstrate the capabilities of WSO2 API Microgateway 3.0. Plus, screencasts that will be shown during this webinar will be published on our blog - so do keep a lookout for them.