WSO2 API Manager in a Nutshell

WSO2 API Manager V2, Component Architecture, Features, Internals and Future

Imesh Gunaratne
Oct 23, 2017 · 14 min read

What is API Management?

APIs provide standard application programming interfaces for application components to talk to each other using well-known protocols. Today almost all software applications use some type of an API for communicating with their internal components, business services, third-party systems, databases, etc. Even though APIs alone can be used for this purpose the growth of the digital enterprises and complex requirements of integrating with various systems may require just more than APIs for meeting consumer needs.

As illustrated in the above figure these requirements may include applying security policies, usage policies, collecting and analyzing statistics, using standard API specifications such as Swagger and OpenAPI for describing APIs, providing proper API documentation, and more importantly providing an API portal for developers to discover APIs with a subscription model. Moving further, developers may also require applying mediation policies for transforming messages, switching protocols, supporting legacy protocols, etc when exposing backend services as APIs. Moreover, API development teams may require a proper API lifecycle management process with version controlling and CI/CD features for allowing different business units and third-party organizations to consume APIs efficiently. In some cases depending on the nature of the business, organizations may also need to monetize the usage of the APIs.

Implementing such complex API management platform with support for wide variety of transports, security features, analytics and usage monitoring, etc from scratch might be a tedious task. Hence, in around the year 2008, 2009 the inception of API management platforms began. According to industry analysts, these solutions started to grow in the early 2010s and its market value in the US alone has been accounted for around USD 140 million in 2014 and expected to grow for around USD 660 million in 2020. Consequently, the global market value is expected to reach USD billions by that time.

What WSO2 has to offer for API Management?

WSO2 released its initial version of API Management platform in year 2012 with nearly six years of experience in implementing it’s widely adopted Enterprise Service Bus (ESB). Now it has reached its second generation with version 2.1.0 and it is being used by many industries leading brands worldwide. At the heart of WSO2 API Manager it uses WSO2 ESB for its gateway runtime, WSO2 Identity Server components for powering the security features and WSO2 Data Analytics Server components for providing API Analytics features. In addition, it also provides workflow management capabilities with human interaction features with WSO2 Business Process Server. It also provides a rich set of user interfaces for managing the API portal, API publisher, monitoring, analytics and administrative features.

WSO2 API Manager is completely free, open source and released under Apache 2.0 license. Unlike any other open source products, it does not have an enterprise version, the same product distribution is used by the open source community and the enterprise customers. Enterprise customers get production support subscriptions, regular bug and security fixes, solution architecture proposals, development services, training, etc as value additions. The key advantages of using WSO2 middleware is that its support for industry standard specifications, protocols, extendibility, open source nature, and the community around it.

WSO2 API Manager Component Architecture

Figure 2: WSO2 API Manager Component Architecture

WSO2 API Manager comprised of eight components; the publisher, portal, gateway, admin portal, traffic manager, key manager, analytics and business process server (BPS). All of these components are implemented in Java using WSO2 Carbon framework and well known open source libraries such as Apache Synapse, Apache Axis2, Apache CXF, Apache Spark, Apache Qpid, Siddhi, etc. The UI components are implemented in Jaggery and JSP. For data storage, MySQL, Postgres, DB2, Oracle, or MS SQL can be used.

1. API Publisher

The API lifecycle management process starts at the API publisher. The API developers will be able to use the publisher UI for designing APIs from scratch or importing existing APIs using Swagger definitions. It supports three main types of APIs; REST, SOAP, and WebSocket and the visibility of the APIs can be controlled by either using user roles or tenants if multi-tenancy is used. If not, APIs can be made available to everyone. REST and SOAP-based APIs can apply failover, or load balancing for their backend service endpoints if required endpoints can also be dynamically configured in the runtime using mediation policies. Out of the box API manager only provides Basic Authentication, Digest Authentication and JWT for managing backend service endpoint security. If any other authentication protocol needs to be used a custom mediation policy can be implemented.

API manager allows backend service responses to be cached for a given time period for improving API performance. In addition, API usage can be controlled at a granular level by using a predefined set of subscription tiers, advanced throttling policies or Siddhi rules. API developers can either use predefined subscription tiers or define their own subscription tiers for restricting API usage according to required levels of throughput. Advanced throttling policies allow users to control incoming requests according to request counts, request message size, client IP addresses, HTTP headers, query parameters, JWT claims, or using any combination. If any of the above request filtering mechanisms do not meet your requirement, an SQL like Siddhi query can be applied to more advanced throttling scenarios:

An example throttling query written in Siddhi:FROM RequestStream
SELECT userId, ( userId == 'admin@carbon.super' ) AS isEligible , str:concat('admin@carbon.super','') as throttleKey
INSERT INTO EligibilityStream;

FROM EligibilityStream[isEligible==true]#throttler:timeBatch(1 min)
SELECT throttleKey, (count(userId) >= 5) as isThrottled, expiryTimeStamp group by throttleKey
INSERT ALL EVENTS into ResultStream;

API publisher allows publishing APIs to multiple gateway environments. For an example in a hybrid cloud deployment APIs can be selectively published to its public cloud API gateways and on-premise API gateways as required. Most importantly, the API publisher allows APIs to be secured using OAuth2. As a result API, resource level authorization rules can be applied using OAuth scopes. For an instant access to an API resource can be granted for a specific user role or a set of user roles via a scope. When the API client subscribes to an API and generates an OAuth token these security rules will be applied.

Publisher portal provides a REST API for executing all of its operations remotely for implementing any client tools. Its API reference can be found on this documentation page.

2. API Portal

The API portal provides a central ecosystem for organizations to publish business APIs including Swagger based API references, documentation, an interactive API console, sandbox APIs, client SDKs, and let their business units, partners, and other third-party users to subscribe to APIs for building business applications. It also provides a user signup page for onboarding API users without requiring any manual intervention. If required, the workflow integration can be enabled for approving user signups. In the portal, APIs can be labeled using tags and API subscriptions can be grouped using API applications. An OAuth2 client id and a client secret will be provided for each API application and OAuth tokens can be generated using that information for accessing all APIs subscribed under the given application. If the API resources have been secured using OAuth scopes, the required scopes would need to be specified when generating the OAuth tokens.

In addition to the core API functionality, the portal also provides features for building a community around the business APIs using an API rating system, forums, and social media features. These might be really useful when exposing APIs to the internet for wider audiences. Furthermore, either using API visibility control or multi-tenancy feature, dedicated API portals can be provided for different business units or organizations using the same API portal deployment.

API portal also provides a REST API for executing all of its operations remotely. Its API reference can be found on this documentation page.

3. API Gateway

The Mediation Engine

As illustrated in the above component architecture diagram WSO2 API Manager has implemented its API gateway component using WSO2 Enterprise Service Bus (ESB). Even though WSO2 ESB has support for collection of transports such as HTTP, JMS, FTP, SMTP, etc API manager has only used HTTP transport for exposing SOAP, REST, and WebSocket APIs. When a request is received at the gateway it will be first picked by the Axis2 HTTP transport receiver and will be handed over to the message builders. If message body needs to be read inside the mediation engine an appropriate message builder will be invoked according to the content type and the message will be de-serialized into a data structure. Otherwise, the message would not be built. Thereafter a set of API handlers will get engaged for executing analytics, applying security policies, throttling policies, usage policies. Once all API handlers accept the API request, it will be handed over to the mediation engine via a REST API or a SOAP service.

Each REST API and SOAP service will have three main flows; In Flow, Out-Flow, and Fault-Flow. Once an API request enters the mediation engine it will reach the In-Flow, execute any mediation policies defined and then send the request message to the backend service endpoint given. Afterwards, the response message will be received either by the Out Flow or for SOAP endpoints if a SOAP error is raised by the backend service, it will reach the Fault Flow. Similar to the In Flow, API developers have the ability engage mediation policies in all three flows. These can be configured via the API publisher. When the API response is delivered back to the API client, the relevant message formatter will get engaged by the Axis2 HTTP transport. That will serialize the message according to the output message format. Both message builders and formatters can be found in the following configuration file:


Synapse API Files

Once an API is published via the API publisher, it gets persisted in the API-M database and at the same time publisher will make an HTTP call to the API gateway for creating a Synapse API definition file in the file system. These API files will be stored in a folder called “api” inside the following gateway instance folder:


In a production system when there is more than one API gateway instance is used, the Synapse API files need to be shared among all those instances. The recommended approach for this is to mount a persistent volume for the above folder path using a Network File System (NFS) and share all Synapse files with all the gateway nodes. In this process, it is important to note that when mounting a volume, the default files found in this folder need to be copied to the volume without making it blank. Otherwise, it would lose the default Synapse files shipped with the product and the gateway would not start.

4. Key Manager

The key manager provides features for creating OAuth applications, generating client id, client secret, generating OAuth tokens, verifying OAuth tokens and APIs for managing the entire OAuth related data set. These features have been implemented using OAuth Carbon features available in WSO2 Identity Server. If required the default key manager implementation can be replaced with any third party key server by implementing the Key Manager Interface and Key Validation Handler.

Token API

The key manager provides the Token API for enabling API users to generate, refresh and revoke OAuth tokens. OAuth tokens can be obtained using a collection of grant types depending on the authentication scheme used by the client application; Password Grant, Client Credentials Grant, Authorization Code Grant, NTLM Grant, SAML Extension Grant, Kerberos OAuth2 Grant, and Refresh Token Grant.

The following example shows how an OAuth token can be obtained using password grant type:

curl -k \ 
-d "grant_type=password&username=Username&password=Password" \
-H "Authorization: Basic <Base64Encoded(client-id:client-secret)>" \ https://wso2apim-gateway:8243/token
"access_token": "69d21f9a-367e-3739-a18f-c29379866ef8",
"refresh_token": "e6650f55-5b7a-33e6-99f6-b3b92008383e",
"scope": "default",
"token_type": "Bearer",
"expires_in": 3600

The below example shows how an expired OAuth token can be refreshed using the refresh token:

curl -k \
-d "grant_type=refresh_token&refresh_token=<refresh_token>" \
-H "Authorization: Basic <Base64Encoded(client-id:client-secret)>" \
-H "Content-Type: application/x-www-form-urlencoded" \ https://wso2apim-gateway:8243/token
"access_token": "fcf6c674-e0c2-3e25-b79f-60aee6d01465",
"refresh_token": "961e10f1-47da-31a4-8e52-007042917e85",
"scope": "default",
"token_type": "Bearer",
"expires_in": 3600

The below example shows how an OAuth token can be revoked:

1curl -vk \
-d "token=<access-token>" \
-H "Authorization: Basic <Base64Encoded(client-id:client-secret)>" \
-H Content-Type: application/x-www-form-urlencoded \

5. Traffic Manager

Figure 6: Traffic Manager Component Architecture

The traffic manager was introduced to WSO2 API Manager in its 2.0.0 release. It uses WSO2 Complex Event Processor (CEP) and WSO2 Message Broker (MB) for processing statistics of incoming API requests in real-time and providing throttling data to the gateway for taking throttling decisions. Once an API request is received by the gateway, the throttling API handler will publish API statistics to the CEP component in traffic manager using Apache Thrift protocol. CEP will execute a set of Siddhi rules according to the throttling policies deployed and publish throttling data to its message broker component using AMQP for reliable delivery. Gateway will subscribe to this topic and populate a set of hash maps for applying throttling rules for incoming API requests without adding much latency to the message flow. The message broker uses an RDBMS for persisting events for providing reliable delivery and each traffic manager instance would need a dedicated database for this purpose. In production, file-based H2 database which is shipped with the product can be used for this purpose because of the level of impact of losing that data is very minimum.

6. Analytics Server

API analytics server receives API statistics via an Apache Thrift listener and executes real-time alerting rules written in Siddhi. At the same time, the raw events get persisted in the analytics database under a group of tables called the events store. API manager ships a set of predefined alerting rules for detecting abnormal API latencies, abnormal backend latencies, abnormal API usage, health availability, abnormal request counts, abnormal API resource access, unseen source IP access, abnormal access token renewal, and tier crossing. Out of the box, these alerts can be sent to a predefined set of email addresses and if required those can also be configured to publish to different output channels including JMS, HTTP, File, SMS, etc with standard CEP functionality. Moreover, users can implement their own alerting rules using Siddhi query language.

The spark scripts will read data persisted in the event store and execute a set of batch processing logic for generating required analytics data to be displayed in the analytics views in the API publisher, API portal, and API admin. These scripts are configured to run every five minutes and processed data will be written to a group of tables in the analytics database called the processed store. These scripts can also be extended for calculating additional analytics as needed.

7. API Admin

The API admin portal provides administrative functions of the WSO2 API Manager. It includes UIs for managing workflow tasks generated by the BPS server, defining alerting configurations, geolocation configurations, advanced throttling policies, application tiers, subscription tiers, custom throttling rules, blacklisting API clients, the live log viewer, and API analytics. Access to admin portal can be controlled using a user role.

8. Business Process Server

The business process server is an optional component in WSO2 API Manager which can be configured and installed if workflow extension features are required. It can intercept standard API management workflows and trigger BPMN, BPEL, and Human Tasks based workflows for user approvals:

The list of workflow extensions and their configurations are stored in the registry in the following registry resource file and it can be updated in runtime without restarting the server:


WSO2 API Manager V3

At the moment this article being written WSO2 API Manager v3 is being implemented. It’s latest milestone releases can be found in the API manager GitHub repository and instructions for trying those out can be found in the root file. This release has been designed group up by making all API management components lightweight and container native using the Carbon v5 framework. As it’s version number may have already implied, it includes major architectural changes for improving some of the drawbacks identified in the current release.

At its core, the existing Apache Synapse based gateway has been replaced with Ballerinalang which is an integration services language and a framework for implementing integration services and mediation engines. In size, the gateway will be around 15 to 20 MB and the gateway would start in around 100 to 200 milliseconds. Next, a message broker has been introduced for distributing API definitions from the API publisher to the gateway nodes. This allows a blank gateway node to get connected to a central message broker cluster and initialize its state using a pub/sub based communication model. Most importantly, it has removed the requirement of having a deployment synchronizer or a shared persistent volume for sharing API definition files among the gateway nodes and the split nature of API definitions which makes it difficult to transactionally synchronize APIs between data centers.

One other important piece which is missing in the current release is an official API Manager CLI. The next major release will include a CLI for completely managing the API manager deployments including features for API migrations. Furthermore, WSO2 API Manager v3 will have the ability to run dedicated API gateway instances for selected groups of APIs and decompose an existing monolithic API deployment into a collection of micro gateway instances for efficient infrastructure utilization. Moreover, it will have integrations with container cluster managers such as Kubernetes, OpenShift, and DC/OS for seamlessly managing its deployments. From the analytics point of view, the existing analytics server will be replaced by the new WSO2 Stream Processor product. It will use Siddhi based stream processing engine for executing both real-time and batch analytics without using Apache Spark.

Last but not least, it will introduce a new authentication scheme for using API keys in addition to OAuth2 tokens which would allow the gateway instances to operate independently without having to connect to a key server for key verifications. This may simplify the deployment process of the gateway instances in DMZs as it would only require gateway instances to connect to the message broker ports for updating its state at runtime.


[1] Wikipedia, API Management

[2] Forrester, The Forrester Wave: API Management Solutions, Q4 2016'RES131050'/reports

[3] WSO2 API Manager 2.1.0 Documentation


Industry best practices for implementing scalable enterprise applications

Imesh Gunaratne

Written by

Engineer at Google



Industry best practices for implementing scalable enterprise applications

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade