This documentation is for WSO2 API Manager 1.10.0 View documentation for the latest release.
Page Comparison - Writing Custom Handlers (v.7 vs v.8) - API Manager 1.10.0 - WSO2 Documentation

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Added a note as to when to use handlers and mediators


  • 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.
  • 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 WSO2 Data Analytics Server (WSO2 DAS) for collection and analysis of statistics. This handler only comes to effect if API usage tracking is enabled. See Working with 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 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.

Writing a custom handler


The outcome of using a Class Mediator vs. a Synapse Handler are very similar. However, when using a custom handler you need to maintain a customized velocity template file that needs to be manually merged when you upgrade your product to a newer version. Therefore, it is recommended to use custom Handlers when you wish to specify the exact order of execution of JARs as this can not be done with Mediators.

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.