The API Gateway has a default mediation flow, which is executed in each API invoke. You can do additional custom mediation for the messages in the API Gateway by extending the mediation flow of the messages. This section explains how.
You can apply mediation extensions in two stages as follows:
- Global Extensions : Apply to all APIs
- Per-API Extensions : Apply only to an intended API
Creating global extensions
An Extension is provided as a synapse mediation sequence. You create mediation extensions through a new sequence. The difference between a global extension and a per-API extension is simply in the name given to the sequence that you use to create it.
Given below is the naming pattern of the sequence to follow when creating a global extension sequence.
WSO2AM--Ext--<DIRECTION>
The <DIRECTION> can be either In or Out. When the direction of the sequence is In, the extension is triggered on the in-flow (request path). When the direction of the sequence is Out, the extension is triggered on the out-flow (response path).
Following is an example synapse configuration of a global extension sequence.
<sequence xmlns="http://ws.apache.org/ns/synapse" name="WSO2AM--Ext--In">
<log level="custom">
<property name="TRACE" value="Global Mediation Extension"/>
</log>
</sequence>
To test the code, copy it to an XML file (e.g., global_ext.xml) and save the file in the <API_Gateway>/repository/deployment/server/synapse-configs/default/sequences directory. The above sequence prints a log message on the console on every API invocation.
Creating per-API extensions
Creating a per-API extension is similar to creating a global extension. The difference is in the sequence naming pattern. Given below is the naming pattern to follow when creating a per-API extension sequence.
<API_NAME>:v<VERSION>--<DIRECTION>
Following is an example synapse configuration of a per-API extension sequence. It is created for an API named admin--TwitterSearch with version 1.0.0.
<sequence xmlns="http://ws.apache.org/ns/synapse" name="admin--TwitterSearch:v1.0.0--In">
<log level="custom">
<property name="TRACE" value="API Mediation Extension"/>
</log>
</sequence>
To test the code, copy it to an xml file (e.g., twittersearch_ext.xml) and save the file in the <API_Gateway>/repository/deployment/server/synapse-configs/default/sequences directory if you are using a standalone server. If you are in a distributed client setup, copy the file to the tenant's synapse sequence folder. For example, if tenant id is 1 then copy it to <API_Gateway>/repository/tenants/1/synapse-configs/default/sequences folder.
The above sequence prints a log message on the console whenever the TwitterSearch API is invoked.
How does this work?
When an API is published from the WSO2 API Publisher, it gets created on the API Gateway. If one inspects the synapse configuration of a created API, he/she will notice that each API has a set of handlers engaged. Following is how it is configured in a given API.
<handlers>
<handler class="org.wso2.carbon.apimgt.gateway.handlers.security.APIAuthenticationHandler"/>
<handler class="org.wso2.carbon.apimgt.usage.publisher.APIMgtUsageHandler"/>
<handler class="org.wso2.carbon.apimgt.usage.publisher.APIMgtGoogleAnalyticsTrackingHandler"/>
<handler class="org.wso2.carbon.apimgt.gateway.handlers.throttling.APIThrottleHandler">
<property name="id" value="A"/>
<property name="policyKey" value="gov:/apimgt/applicationdata/tiers.xml"/>
</handler>
<handler class="org.wso2.carbon.apimgt.gateway.handlers.ext.APIManagerExtensionHandler"/>
</handlers>
The first handler in this handler chain is the APIAuthenticationHandler. The second is the APIMgtUsageHander and likewise. The handler of importance to us for this article is the last handler in the handler chain which is the APIManagerExtensionHandler.
The APIManagerExtensionHandler is the one which triggers the Global as well as Per API extension sequences. It looks for the sequence naming patterns as described above and invokes the sequences accordingly.