This section introduces handlers and using an example, explains how to write a custom handler:
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.
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
MessageContextvariables as appropriate.
APIThrottleHandler:Throttles requests based on the throttling policy specified by the
policyKeyproperty. Throttling is applied both at the application level as well as subscription level.
APIMgtUsageHandler:Publishes events to WSO2 Stream Processor (WSO2 SP) for collection and analysis of statistics. This handler only comes to effect if . See the Working with Analytics section for more information.
APIMgtGoogleAnalyticsTrackingHandler:Publishes events to Google Analytics. This handler only comes into effect if Google analytics tracking is enabled. See 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.xmlfile 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.
Message logging is handled by
APILogMessageHandler is a sample handler that comes with WSO2 API Manager that can be used for logging.
Why are logs removed from
The primary purpose of
ExtensionHandler is handling extensions to mediation and not for logging messages. When the logs are also included in
ExtensionHandler, there's a limitation to improve the
ExtensionHandler for developing features because it breaks the logs.
For example, When the
ExtensionHandler moves to the top of the handlers set, most of the logs print null values since the handler runs before the
APIAuthenticationHandler. Therefore, the logs are removed from the extension handler and
APILogMessageHandler introduced as a sample.
To achieve logging requirements, this handler is not the only approach and with custom sequences also it is possible to log messages using the Log Mediator.
In order to enable logging by invoking
APILogMessageHandler, follow the steps below.
To enable Message Logging per API :
Open the synapse Configuration of the API located in
<APIM_HOME>/repository/deployment/server/synapse-configs/default/apidirectory and add below handler before
Copy the following code into the
<APIM_HOME>/repository/conf/log4j.propertiesfile to enable printing DEBUG logs.
Restart API Manager.
To enable Message Logging into APIS created from publisher automatically :
Open the <APIM_HOME>/repository/resources/api_templates/velocity_template.xml file and copy the following handler beofore </Handlers>.
- Restart API Manager.
To perform analytics with the logs, see Analyzing the Log Overview.
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.
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 org.apache.synapse.rest.AbstractHandler 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.
Given below is an example implementation. Please find the complete project archive org.wso2.carbon.test.authenticator.zip. You can download, unzip and build the project using maven and Java 7/8.
Engaging the custom handler
- Build the custom authenticaor code downloaded previously, and copy the resulting jar to <API-M_HOME>/repository/components/dropins directory.
Engage the custom handler using the API template as explained below:
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
It is not recommended to update the API source code via the source view UI or file system when engaging a custom handler to selected APIs, because the customizations get overridden by the publisher updates.
For example, the following code segment adds the custom authentication handler that you wrote earlier to the
velocity_template.xmlfile while making sure that it skips the default
You can select to which API(s) you need to engage the handler. Given below is an example of adding only the
CustomAPIAuthenticationHandlerto the sample PizzaShackAPI.
- Restart the API Manager server.