Adding Mediation Extensions

The API Gateway has a default mediation flow for each API invocation. You can do additional custom mediation for the messages in the API Gateway by extending its mediation flow using a synapse mediation sequence. You can create a sequence in the following ways:

Using the tooling support to create a sequence

The recommended way to create an API is to a tool like WSO2 Developer Studio. You can then engage the sequence it to the API using the API Publisher. This tutorial explains the steps: Engage a Custom Mediation Flow.

Manually creating a sequence

You can manually create mediation extensions globally or per API. 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.

Tip: You do not have to follow this naming convention if you plan to engage the sequence/s to the API/s through the API Publisher.

Creating global extensions

Given below is the naming pattern of a global extension sequence.

WSO2AM--Ext--<DIRECTION>

The <DIRECTION> can be In or Out. To change the default fault sequence, you can either modify the default sequence or write a custom fault sequence and engage it to APIs through the API Publisher. When the direction of the sequence is In, the extension is triggered on the in-flow (request path). Similarly, when the direction of the sequence is Out, the extension is triggered on the out-flow (response path). Shown below is an example synapse configuration of a global extension sequence.

Global Extension Sequence Example

<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 <APIM_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

Given below is the naming pattern of a per-API extension sequence.

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

Shown below 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.

API Extension Sequence Example

<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>

The tenant username must be given as <username>-AT-<domain> in the configuration. For example, if the tenant username is testuser and the domain is wso2.com, then the name attribute in the above configuration must be testuser-AT-wso2.com--TwitterSearch:v1.0.0–In. The @ sign must be given as AT.

To test the code, do the following:

In the single-tenant mode, copy it to an XML file (e.g., twittersearch_ext.xml) and save the file in the <APIM_HOME>/repository/deployment/server/synapse-configs/default/sequences directory
In the multi-tenant mode, 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 API is invoked.