Implementing custom handler for WSO2 API Manager

5 min readNov 22, 2020

Hello everyone !!! Hope you all are safe and safety.

I am very glad to say that I started my career life as Software Engineer Intern at WSO2.

Today I hope to share my knowledge on WSO2 custom handler and implementation of a custom handler step by step which needs to complete my project at WSO2.

In this article, you will get to know:

A brief idea on how WSO2 API Gateway works in WSO2 API Manager

What is a handler

Default Handlers

Implementation of a handler step by step

Lets look at overview of API Gateway in WSO2 API Manager.

What is API Gateway ?

An API Gateway is an API management tool that sits between a client and a collection of back-end services. An API gateway acts as a reverse proxy to accept all application programming interface (API) calls, aggregate the various services required to fulfill them and return the appropriate result.

WSO2 API Gateway

WSO2 API Gateway provides a runtime and a backend component (an API proxy) for API calls. It secures, protects, manages, and scales API calls by intercepting API requests and applying policies, such as throttling and security, using handlers and managing API statistics.

Upon validation of a policy, the Gateway passes Web service calls to the actual backend. If the service call is a token request, the Gateway passes it directly to the Key Manager.

What is a handler?

A handler is one of the processes that an API invocation goes through when it travels through the Gateway component . These handlers are executed sequentially and by default in the order as shown below.

Let’s see what each handler does:

CORSRequestHandler: Sets the CORS headers to the request and executes the CORS sequence mediation logic. This handler is thereby responsible for returning the CORS headers from the gateway or routing the requests to the backend and letting the backend send the CORS headers.

This is an optional setting that will be triggered when Enable API based CORS Configuration is checked.

APIAuthenticationHandler: Validates the OAuth2 bearer token used to invoke the API. It also determines whether the token is of type Production or Sandbox and sets MessageContext variables as appropriate.

Again, this handler is optional, in the sense that if there is no token required for the API or an URI Template the handler will either not be invoked or it will return almost directly after invocation.

APIThrottleHandler: Throttles requests based on the throttling policy specified by the policyKey property. Throttling is applied both at the application level as well as subscription level.

APIMgtUsageHandler: Publishes events to WSO2 Data Analytics Server (WSO2 DAS) for collection and analysis of statistics. This handler only comes to effect if API usage tracking is enabled.

APIMgtGoogleAnalyticsTrackingHandler: Publishes events to Google Analytics. This handler only comes into effect if Google analytics tracking is enabled.

APIManagerExtensionHandler : Triggers extension sequences. By default, the extension handler is listed at last in the handler chain, and therefore is executed last. To configure the API Gateway to execute extension handler first, uncomment the <ExtensionHandlerPosition> section in the <APIM_HOME>/repository/conf/api-manager.xml file and provide the value top. What is executed are sequences on the IN-, OUT- and Faultflow. This is optional and should be checked when publishing the API.

Lets see how to implement a handler.

Create a maven project called handlers.

Create a java class as NameHandler.java as below.

Add dependencies as below.

The NameHandler extends the AbstractHandler and implements the ManagedLifecycle that among other things allows for the release of used resource. The handleRequest and handleResponse both return true after putting a message on the console.

Run mvn clean install . It makes a jar file in .m2 folder.

After that copy the jar file [APIM-HOME]/repository/components/lib and restart the API Manager. The jar files are not hot deployed.

Engaging the custom handler

You can engage a custom handler to all APIs at once or only to selected APIs. To engage a custom handler to APIs, you need to add the custom handler with its logic in the <APIM_HOME>/repository/resources/api_templates/velocity_template.xml file.

Add <handler class=”org.zina.handler.NameHandler”/> in velocity_template.xml file.

I’ve deployed the sample API (Pizzashack) on the API Manager and will change that file (PizzaShackAPI.xml)in [APIM-HOME]/repository/deployment/server/synapse-configs/default/api

Add <handler class=”org.zina.handler.NameHandler”/> to PizzaShackAPI.xml .