This documentation is for WSO2 API Manager 1.9.0. View documentation for the latest release.
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 8 Next »

This section introduces handlers and using an example, explains how to write a custom handler: 

Introducing Handlers

When an API is created, a file with its synapse configuration is added to the API Gateway. You can find it in the <APIM_HOME>/repository/deployment/server/synapse-configs/default/api folder. It has a set of handlers, each of which is executed on the APIs in the same order they appear in the configuration. You find the default handlers in any API's Synapse definition as shown below.

   <handler class=""/>
   <handler class="org.wso2.carbon.apimgt.gateway.handlers.throttling.APIThrottleHandler">
        <property name="id" value="A"/>
        <property name="policyKey" value="gov:/apimgt/applicationdata/tiers.xml"/>
   <handler class="org.wso2.carbon.apimgt.usage.publisher.APIMgtUsageHandler"/>
   <handler class="org.wso2.carbon.apimgt.usage.publisher.APIMgtGoogleAnalyticsTrackingHandler"/>
   <handler class="org.wso2.carbon.apimgt.gateway.handlers.ext.APIManagerExtensionHandler"/>

Let's see what each handler does:

  • 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. 
  • 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 BAM for collection and analysis of statistics. This handler only comes to effect if API usage tracking is enabled. See Publishing API Runtime Statistics for more information.
  • APIMgtGoogleAnalyticsTrackingHandler: Publishes events to Google Analytics. This handler only comes into effect if Google analytics tracking is enabled. See Integrating with Google Analytics for more information.
  • APIManagerExtensionHandler: Triggers both global as well as per-API extension sequences. It reads the sequence names and determines what APIs must be invoked. By default, the extension handler is listed at last in the handler chain, and therefore is executed last. You can configure the API Gateway to execute extension handlers first by uncommenting the <ExtensionHandlerPosition> section in the <APIM_HOME>/repository/conf/api-manager.xml file and providing the value top. This is useful when you want to execute your own extensions before our default handlers. See Adding Mediation Extensions.

Writing a custom handler

Let's see how you can write a custom handler and apply it to the API Manager. In this example, we extend the authentication handler. 

WSO2 API Manager provides the OAuth2 bearer token as its default authentication mechanism. The source code of the implementation is here. Similarly, you can extend the API Manager to support any custom authentication mechanism by writing your own authentication handler class. This custom handler must extend class and implement the handleRequest() and handleResponse() methods.

Given below is an example implementation:


import org.apache.synapse.MessageContext;
import org.apache.synapse.core.axis2.Axis2MessageContext;

import java.util.Map;

public class CustomAPIAuthenticationHandler extends AbstractHandler {

    public boolean handleRequest(MessageContext messageContext) {
        try {
            if (authenticate(messageContext)) {
                return true;
        } catch (APISecurityException e) {
        return false;

    public boolean handleResponse(MessageContext messageContext) {
        return true;  

    public boolean authenticate(MessageContext synCtx) throws APISecurityException {
        Map headers = getTransportHeaders(synCtx);
        String authHeader = getAuthorizationHeader(headers);
        if (authHeader.startsWith("userName")) {
            return true;
        return false;

    private String getAuthorizationHeader(Map headers) {
        return (String) headers.get("Authorization");

    private Map getTransportHeaders(MessageContext messageContext) {
        return (Map) ((Axis2MessageContext) messageContext).getAxis2MessageContext().

Engaging the custom handler

You can engage the custom handler per API or to all APIs at once. To engage to all APis, the recommended approach is to add it to the velocity template. Given below is how to engage handlers to a single API, by editing its source view.

Note that when you engage a handler by editing the API's source view, your changes will be lost every time you update and save the API through the API Publisher.

  1. Build the class and copy the JAR file to <APIM_HOME>/repository/components/lib folder.
  2. Log in to the management console and select Service Bus > Source View in the Main menu.
  3. In the configuration that opens, select an API and navigate to the <Handlers> section. The following line appears as the first handler. This is the current authentication handler used in the API Manager.

  4. Replace the above line with the handler that you created. It will engage your custom handler to the API Manager instance. According to this example, it is as follows:

    <handler class=""/>
  • No labels