Customizing API Template

When an API is published and deployed in the Gateway, corresponding API is generated and deployed in the gateway in-memory.

An API's gateway configuration file(Synapse configuration) content contains API metadata, API resource information, properties etc and it is generated based on the API template file which can be found in <APIM_HOME>/repository/resources/api_templates/velocity_template.xml location. You can modify the default API template definition in order to customize the synapse configurations of the API.

Engaging a custom handler based on API Properties

In API Manager, you can implement and engage custom handlers to customize the default mediation flow of API requests. See Writing a custom handler for more information. The API properties can be used to conditionally engage these custom handlers for APIs.

Following steps illustrate how you can enable a custom handler for a selected set of APIs which are having a particular property value.

1. Open <APIM_HOME>/repository/resources/api_templates/velocity_template.xml file and locate the handlers definition.

2. Add following definition to engage the custom handler.

   In this example, org.wso2.apimgt.custom.CustomAPIAuthenticationHandler will be engaged as the custom handler for APIs which are having custom_authentication property value.

   Example 1 - Engaging as a new handler

   <handlers xmlns="http://ws.apache.org/ns/synapse">
   
    ##Engage the Custom handler based on 'custom_authentication' propert value
    #if($apiObj.additionalProperties.get('custom_authentication') == "true"))
      <handler class="org.wso2.apimgt.custom.CustomAPIAuthenticationHandler"/>
    #end
   
   #foreach($handler in $handlers)
   <handler xmlns="http://ws.apache.org/ns/synapse" class="$handler.className">
       #if($handler.hasProperties())
       #set ($map = $handler.getProperties() )
       #foreach($property in $map.entrySet())
       <property name="$!property.key" value="$!property.value"/>
       #end
       #end
   </handler>
   #end
   ## check and set enable schema validation
   #if($enableSchemaValidation)
   <handler class="org.wso2.carbon.apimgt.gateway.handlers.security.SchemaValidator"/>
   #end
   </handlers>
   

   Example 2 - Switching the custom handler with one of the default handlers

   <handlers xmlns="http://ws.apache.org/ns/synapse">
   #foreach($handler in $handlers)
   
   ##Switch the custom handler with default authentication handler for APIs which are having `custom_authentication=true` property 
           #if(($handler.className =="org.wso2.carbon.apimgt.gateway.handlers.security.APIAuthenticationHandler") && ($apiObj.additionalProperties.get('custom_authentication') == "true"))
                           <handler class="org.wso2.apimgt.custom.CustomAPIAuthenticationHandler"/>
           #else
                   <handler xmlns="http://ws.apache.org/ns/synapse" class="$handler.className">
                           #if($handler.hasProperties())
                           #set ($map = $handler.getProperties() )
                           #foreach($property in $map.entrySet())
                           <property name="$!property.key" value="$!property.value"/>
                           #end
                           #end
                   </handler>
           #end
   #end
   </handlers>
   

   Likewise, you can implement the logic to conditionally enable/disable custom or default handlers.

   Info

   If you are using a distributed API Manager deployment (i.e., Publisher, Devportal, Gateway and Key Manager components are running on separate JVMs), edit the template in the Publisher node.

3. Save the changes.

4. Add custom_authentication=true as an additional property for those APIs which you need to enable the custom handler.

   

5. Publish the API to gateway, and you will notice that the custom handler has been enabled for APIs which are configured with the custom property.

   <handlers>
           <handler class="org.wso2.apimgt.custom.CustomAPIAuthenticationHandler"/>
           ....
   </handlers>   
   

API Template Variables

Following set of variables are available at API template level. You can use these variable values to implement your own customization logic.

Variable Name	Description
apiName	Name of the API
apiVersion	The version of the API
apiContext	The context of the API
apiIsBlocked	Is API blocked or not
endpoint_config	API Endpoint configuration in json
handlers	The default handler set