The API Gateway has a default mediation flow that is executed in each API invocation. You can do additional custom mediation for the messages in the API Gateway by extending its mediation flow. An extension is provided as a synapse mediation sequence. You create a custom mediation sequence either manually or using a tool like WSO2 Developer Studio, and then engage it per API or globally to all APIs of a specific tenant.
There are two ways to apply mediation extensions to messages:
- : Apply only to an intended API
- : Apply to all APIs
The difference between a per-API extension and a global extension is simply in the name given to the sequence that you use to create it.
Creating per-API extensions
Create and upload to the registry
Create a custom mediation sequence either manually or using a tool like WSO2 Developer Studio, and store the
sequence.xml file in the governance registry. For more information, see Creating ESB Artifacts in the Developer Studio documentation. The registry collection where sequences are stored is
customsequences, which is available by default in
apimgt governance registry location. Given below are the registry paths:
For example, if you have an
in sequence file,
testInSequence, you must save it in the
Once you create the XML file, upload it to the registry using the management console UI.
- Open the API-M management console (https://localhost:9443/carbon with admin/admin as the default credentials) and select Resources > Browse.
- Navigate to the
- Click Add Resource to upload the XML file.
Once an extension sequence has been uploaded to the registry, you can attach it to an API using the API Publisher Web interface at the time the API is created. Log in to the API Publisher (https://localhost:9443/publisher) and click Add from the left panel. In the Add New API page that opens, navigate to the Manager section where you find Sequences. There, you can select
In/Out/Fault sequences for the API from the drop-down lists. For example,
Create and save in the file system
Create a custom mediation sequence either manually or using a tool like WSO2 Developer Studio. For more information, see Creating ESB Artifacts in the Developer Studio documentation. You can name the mediation XML file in the pattern
<API_NAME>:v<VERSION>--<DIRECTION> and save it directly in the following location:
- In the single-tenant mode, save the XML file in the
- In the multi-tenant mode, save the XML file in the tenant's synapse sequence folder. For example, if tenant id is 1, then save it in
In the naming pattern, the
<DIRECTION> can be
Out. When it is
In, the extension is triggered on the in-flow (request path) and when it is
Out, the extension is triggered on the out-flow (response path). 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.
An example synapse configuration of a per-API extension sequence created for the API
admin--TwitterSearch version 1.0.0 is given below.
NOTE: 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.
You can copy this content into an XML file (e.g.,
twittersearch_ext.xml) and save it in the
The above sequence prints a log message on the console whenever the
TwitterSearch API is invoked.
Creating global extensions
You can also engage mediation extension sequences to all APIs of a specific tenant at once. To do that, simply create the XML file with the naming pattern
WSO2AM--Ext--<DIRECTION> and save it in the
<API-M_HOME>/repository/deployment/server/synapse-configs/default/sequences directory. The
<DIRECTION> can be
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.
An example synapse configuration of a global extension sequence is given below:
To test the code, copy it to an XML file (e.g., global_ext.xml) and save the file in the
<API-M_HOME>/repository/deployment/server/synapse-configs/default/sequences directory. The above sequence prints a log message on the console on every API invocation.
Executing extension sequences
When an API is published, a file with its synapse configuration is created on the API Gateway. This synapse configuration has a set of handlers as shown in the following example:
The handler, by the name
APIManagerExtensionHandler, triggers both global as well as per-API extension sequences. It reads the sequence names and determines what APIs must be invoked. By default, the extension handler is listed at last in the handler chain, and therefore is executed last. You can configure the API Gateway to execute extension handlers first. To do that, open the
<API-M_HOME>/repository/conf/api-manager.xml file, uncomment the
<ExtensionHandlerPosition> section and provide the value
top as follows:
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.