Page Comparison

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

...

• 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 Using WSO2 DAS 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 extension sequences. By default, the extension handler is listed at last in the handler chain, and therefore is executed last. You cannot change the order in which the handlers are executed, except the extension handler. 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. This is useful when you want to execute your own extensions before our default handlers in situations like  doing additional security checks such as signature verification on access tokens before executing the default security handler.  

• See Adding Mediation Extensions.

Using APILogMessageHandler

Prior to API Manager 1.9.1 version, this message logging is handled by APIManagerExtensionHandler. Addition to the above mentioned Handlers, from API Manager version 1.9.1 onwards APILogMessageHandler has introduced. APILogMessageHandler is a sample handler comes with WSO2 API Manager that can be used for logging.

Inorder to enable logging by invoking APILogMessageHandler, follow below steps.

To enable Message Logging per API : 

1. Open the synapse Configuration of the API located in <APIM_HOME>/repository/deployment/server/synapse-configs/default/api directory and add below handler before </Handlers>.

   Code Block
   <handler class="org.wso2.carbon.apimgt.gateway.handlers.logging.APILogMessageHandler"/>

2. Copy the following code into the <APIM_HOME>/repository/conf/log4j.properties file to enable printing DEBUG logs.

   Code Block
   log4j.logger.org.wso2.carbon.apimgt.gateway.handlers.logging.APILogMessageHandler = DEBUG

3. Restart API Manager server.

To enable Message Logging into APIS created from publisher automatically : 

1. Open velocity_template.xml file located in <APIM_HOME>/repository/resources/api_templates directory and copy the following handler beofore </handlers>.

   Code Block
   <handler class="org.wso2.carbon.apimgt.gateway.handlers.logging.APILogMessageHandler"/>

2. Restart API Manager server.

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. Make sure your custom handler name is not the same as the name of an existing handler. 

...

package org.wso2.carbon.test;

import org.apache.synapse.MessageContext;
import org.apache.synapse.core.axis2.Axis2MessageContext;
import org.apache.synapse.rest.AbstractHandler;
import org.wso2.carbon.apimgt.gateway.handlers.security.APISecurityException;
import java.util.Map;

public class CustomAPIAuthenticationHandler extends AbstractHandler {
   
    private static final Logger logger = LoggerFactory.getLogger(CustomAPIAuthenticationHandler.class);

    public boolean handleRequest(MessageContext messageContext) {
        try {
            if (authenticate(messageContext)) {
                return true;
            }
        } catch (APISecurityException e) {
            logger.error();
        }
        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().
                getProperty(org.apache.axis2.context.MessageContext.TRANSPORT_HEADERS);
    }
}

...

You can engage a custom handler to all APIs at once or only to selected APIs. 

To engage to all APIs, the recommended approach is to add it to the <APIM_HOME>/repository/resources/api_templates/velocity_template.xml file. For example, the following code segment adds the custom authentication handler that you wrote earlier to the velocity_template.xml file while making sure that it skips the default APIAuthenticationHandler implementation:

<handler class="org.wso2.carbon.apimgt.custom.authentication.handler.CustomAPIAuthenticationHandler" />
       #foreach($handler in $handlers)
          #if(!($handler.className == "org.wso2.carbon.apimgt.gateway.handlers.security.APIAuthenticationHandler"))
           <handler xmlns="http://ws.apache.org/ns/synapse" class="$handler.className">
            #if($handler.hasProperties())
                #set ($map = $handler.getProperties() )
                #foreach($property in $map.entrySet())
                    <property name="$!property.key" value="$!property.value"/>
                #end
            #end
           </handler>
         #end
        #end
</handlers>

 Given below is how to engage handlers to a single API, by editing its source view.

...