Introduction to WSO2 API Microgateway

Introduction to WSO2 API Microgateway

  • By Sanjeewa Malalgoda
  • 6 Aug, 2018

What is WSO2 API Microgateway?

WSO2 API Microgateway is a lightweight message processor for APIs. It is used for message security, transport security, routing, and other common API management related quality of service (QoS) functions. It can process incoming and outgoing messages while collecting information required for usage metering and throttling.

The microgateway natively supports scaling in highly decentralized environments such as microservice architecture. An immutable, ephemeral microgateway fits microservice architecture very well too. It is also capable of operating in lockdown environments such as in IoT devices since connectivity to the API management system from the microgateway is not mandatory.

Setting up microgateways closer to your backend servers and on-premise not only reduces network latency but also enhances security as you can run it in a fully controlled environment with a selected set of APIs. You can run the microgateway in the regional data center where your service implementation runs or if needed you can do the same in your local workstation as well.

In summary, a microgateway is a simplified, lightweight version of the API gateway. However, a microgateway only supports a subset of capabilities that an API gateway provides.

Key Advantages of an API Microgateway

Some advantage of using an API microgateway have been listed below.

Fits microservice architecture: Characteristics of a microgateway allows it to fit well into microservice architecture. Since microgateways have a small startup delay and consume fewer resources, it natively supports container-based deployments. When there is a requirement to scale, this can be done easily because of its design. Immutable, ephemeral gateways help to build cloud native API management solutions and if we have simple and infinitely repeatable deployments which use continuous integration/delivery it would be much easier with microgateways. Also, with these capabilities, server and node failures don’t result in your service going down.

Accelerate development: Unlike a full API gateway, users can easily run a selected set of APIs in a controlled environment within seconds using a microgateway. For example, if a developer needs to quickly debug an API invocation flow, then he can simply setup the microgateway in their local workstation without doing a full-blown deployment.

Low resource consumption and high efficiency: A microgateway can run with very low memory and CPU consumption. Its lightweight design allows it to load the minimum required components to process API calls.

Reduce network latency: Users can deploy the microgateway closer to their backend services when required. If needed, the microgateway can be deployed in a regional data center or the same subnet that your services reside in. With this, you don’t need to route your API calls through the Internet or different network segments.

DevOps friendly: No programming is needed to setup and manage a microgateway. It can be done only using configurations or environment variables that can override configurations. Also, if needed, you can easily integrate microgateway management with a container management system and automate the deployment process.

Enhanced security: If your API consumer and producer both reside in the same network or in close proximity then there is no point of routing that traffic through a cloud gateway. We can simply route the traffic through the microgateway. This helps to reduce network latency. Also, routing traffic within the same network boundaries help address security concerns and become compliant with certain regulations.

Here are a few scenarios where using a microgateway is advised:

  • When you need to run the gateway in a lockdown environment or offline mode, which don’t have a connection to the API management system
  • When running a set of selected API in a controlled environment such as private jet gateway mode. Especially when we see an unusual traffic pattern on one API or set of selected APIs and need to scale it alone.
  • An internal or on-premise API gateway deployment where you have consumers (delivery channels) and service instances residing within the same network. In such cases having a microgateway within close proximity to the backend server will reduce latency.
  • When there is a requirement to run the gateway in sidecar mode along with an application server within the same runtime (or same pod in the Kubernetes world)

Here's when you should use an API gateway:

  • When there is a requirement to throttle API calls based on counters across all gateway nodes
  • When you need to run the API gateway as a centralized gateway that can handle requests for many different APIs and backend servers
  • In traditional SOAP architecture, which requires the gateway to perform mediations and orchestrations

How an API Microgateway Works

WSO2 API Manager comes with a microgateway toolkit which is responsible for microgateway related management tasks. This command line tool accepts commands issued by the user. It communicates with the API management core runtime (API publisher) to retrieve API metadata that is required to create the microgateway runtime.

  • Once the API Gateway command-line interface (CLI) setup happens, users are supposed to provide their credentials and some other details about gateway environment they need to setup. With this information, the CLI can communicate with APIs exposed from the API core. Then it will create the gateway runtime project for a given label. That will include all the APIs under a given label and create all the throttling policies that you need for the runtime.
  • Then when the user issues a build command it will build the project and create a single distribution with API definitions. Users can directly run this in their cloud, on-premise, or local workstation deployment as per their requirement.

Figure 1: How the microgateway toolkit works with WSO2 API Manager

Hybrid API Management Deployment with API Microgateway

Most API management solutions have some sort of API gateway within their component stack. Typically it acts as the policy enforcement point and usage metering agent for API calls. It can also add some other QoS functions. If the API management solution is offered as a SaaS, then this gateway is typically running on a cloud deployment and users can access it through the Internet.

Some organizations have strict security requirements due to internal policies and all API traffic management through the gateway must be done on-premise. As discussed above there are some other advantages like reduced network latency also available with on-premise deployments.

When you need to leverage the advantages of both these deployments, you should go for a hybrid solution. Hybrid API management isn’t a new thing for us at WSO2 and we’ve supported it for last few years. The WSO2 solution to hybrid API management involves having a centrally controlled API management system with a set of on-premise gateways.

Figure 2

In hybrid API management deployments we will need to deploy gateways in a regional or on-premise data center. Most of the time these deployments contain just a gateway runtime. Since the microgateway design addresses requirements such as low startup time, less resource consumption and ease of configuration, it would be the ideal solution for regional on-premise deployments and can be used for cloud deployments as well.

API Microgateway and Analytics

When API traffic is routed through the API gateway, the incoming and outgoing messages are read and processed asynchronously to generate usage data. This asynchronous process allows the gateway to process messages without adding an additional overhead to the API invocation time. After extracting the required information from the messages they will publish it to specific streams and eventually write it to a file system.

In the gateway we have configured a periodic task to read these usage data files from time to time and send them to the central API Management system's analytics node as a compressed file stream. So the analytics node can read these files and summarize them as usual. Then from that point onwards, the analytics process has no difference in the microgateway scenario from the default synapse based gateway.

API Microgateway Security

The Role of an API Management System

As discussed before, the WSO2 API Microgateway Toolkit needs to communicate with the WSO2 API Manager runtime to retrieve all API metadata that's needed to bootstrap the gateway runtime. The WSO2 API Manager runtime plays an important role as it manages all client applications and access tokens among other things.

  • Whenever the user needs to consume an API which is deployed in the microgateway, the user will need to go to the API store and subscribe to that API. Then the usual process follows where the user needs to generate an access token or self-contained token to invoke the API. None of these user flows are different for the microgateway.
  • Since microgateways don't have access to any persistence store or database it doesn't communicate with the central API management system via file access or direct database calls. The microgateway will communicate only via web service calls. Later we will see how that communication happens.

Client App Authentication

  • Microgateways support client authentication through OAuth 2.0 based access tokens and self-contained tokens that the end user can obtain.
  • The self-contained token will be validated within the microgateway itself and communication with central API management runtime is not needed. So if you need an offline gateway then self-contained tokens are the ideal solution for that.
  • But when the user passes OAuth 2.0 based access tokens, the microgateway will communicate with central API management system to validate the access tokens. The main reason to perform this call is to retrieve additional information required to build authentication context within the microgateway.


The API microgateway is a simplified version of the API gateway which fits into microservice architecture very well. Some of its characteristics such as its immutabile and ephemeral nature, low resource consumption, efficiency, and fast booting time help users to implement better deployment strategies including hybrid API management. Most importantly, WSO2 API Manager allows developers to experiment with the microgateway while the battle-proven API gateway and other components are used in their deployments.

About Author

  • Sanjeewa Malalgoda
  • Associate Director, Engineering | Architect at WSO2
  • WSO2