This documentation is for WSO2 API Manager 2.1.0. View documentation for the latest release.

All docs This doc

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.



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.

Custom Handler is a way of extending API Manager which the product offer to change the API flow through the API Gateway. What is happening in custom handler can be decided by the code you are writing to extend the product. It can be adding extra security, logging database invocation or something else. This custom handler must extend the class and implement handleRequest() and handleResponse() methods.

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. 

WSO2 API Manager provides the OAuth2 bearer token as its default authentication mechanism. A sample 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: