Versions Compared

Old Version 9

changes.mady.by.user Former user

Saved on

compared with

New Version 10

changes.mady.by.user Former user

Saved on

Key

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

This section introduces handlers and uses an example to explain how to write a custom handler: 

Table of Contents
maxLevel3
minLevel3

Introducing handlers

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.

...

  • 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 the Analytics section 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 Message logging is handled by APIManagerExtensionHandler for API Manager 1.9.1 version, this message logging is handled by APIManagerExtensionHandlerand above. Addition to the above mentioned Handlers, APILogMessageHandler has introduced from API Manager version 1.9.1 onwards APILogMessageHandler has introducedonwards. APILogMessageHandler is a sample handler that comes with WSO2 API Manager that can be used for logging.

Info

Why are logs have removed from APIManagerExtensionHandler?

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. Due to this fact,it was decided to remove Therefore, the logs are removed from the extension handler and APILogMessageHandler introduced as a sample.

Note

Note that, to 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 In order to enable logging by invoking invoking APILogMessageHandler, follow the steps 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 before </Handlers>.

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

  2. Copy the following code into the <APIMthe <APIM_HOME>/repository/conf/log4j.properties file to  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 the <APIM_HOME>/repository/resources/api_templates directory and /velocity_template.xml file and copy the following handler beofore </handlers>Handlers>.

    Code Block
    <handler class="org.wso2.carbon.apimgt.gateway.handlers.logging.APILogMessageHandler"/>
  2. Restart API Manager server.

Note

If you want to do To perform analytics with the logs refer , see Analyzing the Log Overview.

...

You can engage a custom handler to all APIs at once or only to selected APIs. To engage a custom handler to APIs, y ou need to add the custom handler with its logic  in the  <APIM_HOME>/repository/resources/api_templates/velocity_template.xml file. 

Note

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.xml file while making sure that it skips the default APIAuthenticationHandler implementation:

...