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 BAM for collection and analysis of statistics. This handler only comes to effect if . 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 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.
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.
Why logs have removed from
The primary purpose of ExtensionHandler is handling extensions to mediation and not for logging messages. When the logs 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. Due to this fact,it was decided to remove the logs from extension handler and APILogMessageHandler introduced as a sample.
Note that, 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.
Inorder to enable logging by invoking APILogMessageHandler, follow below steps.
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 </Handlers>.
Copy the following code into the <APIM_HOME>/repository/conf/log4j.properties file to enable printing DEBUG logs.
Restart API Manager server.
To enable Message Logging into APIS created from publisher automatically :
Open velocity_template.xml file located in <APIM_HOME>/repository/resources/api_templates directory and copy the following handler beofore </handlers>.
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.
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
org.apache.synapse.rest.AbstractHandler class and implement the
Given below is an example implementation:
Engaging the custom handler
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
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 overwritten every time you save the API through the API Publisher.
- Build the class and copy the JAR file to
- Log in to the management console and select Service Bus > Source View in the Main menu.
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.
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: