Page Comparison

The API Gateway has a default mediation flow, which is executed in each API invokeinvocation. You can do additional custom mediation for the messages in the API Gateway by extending the their mediation flow of the messages. This section explains how.You can apply mediation extensions in two stages . An extension is provided as a synapse mediation sequence.

There are two ways to apply mediation extensions to messages. They are as follows:

• Global Extensions : Apply to all APIs
• Per-API Extensions : Apply only to an intended API

...

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.

Creating global extensions

Anchor
GlobalExtension GlobalExtension

Given below is the naming pattern of the sequence to follow when creating 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 itthe code, copy this code it to an XML file (e.g., global_ext.xml) and save it the file in the <API<APIM_Gateway>HOME>/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

Anchor
APIExtension APIExtension

 Creating a Per API Extension is similar to the Global Extension. The only difference is in the sequence naming pattern. Following is the Given below is the naming pattern to follow when creating a Per per-API Extension extension sequence.

...

...

<API_NAME>:v<VERSION>--<DIRECTION>

Following is an example synapse configuration of a Per per-API Extension 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 see this at work, copy this content into To test the code in super-tenant mode, copy it to an xml file (e.g., twittersearch_ext.xml) and save it the file in the <API<APIM_Gateway>HOME>/repository/deployment/server/synapse-configs/default/sequences directory . If its tenant you need to copy it to tenants if you are using a standalone server. In multi-tenant mode, copy the file to the tenant's synapse sequence folder (e. g 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.

...

Invoking the extension sequences

When an API is published from the WSO2 API Publisher, it , a file with its synapse configuration gets created on the API Gateway. If one inspects you inspect the synapse configuration of a created an API, he/she will notice that each API has you will see a set of handlers engaged. Following is how it is configured in a given API.

...

as shown in the following example:

<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 accordinglyThe handler by the name APIManagerExtensionHandler triggers both global as well as per-API extension sequences. It reads the sequence names and determine what APIs need to be invoked.

By default, the extension handler is listed at last in the handler chain, and therefore is executed at last. You can configure the API Gateway to execute extension handlers first. To do that, open <APIM_HOME>/repository/conf/api-manager.xml file, uncomment the <ExtensionHandlerPosition> element and provide the value top as follows:

<ExtensionHandlerPosition>top</ExtensionHandlerPosition>

This is useful when you want to execute your own extensions before our default handlers. For example, if you want to have additional security checks such as signature verification on access tokens before executing the default security handler, you can define an extension and configure the Gateway to execute extension handlers first.

For more information on Handlers, see  Architecture Components.