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 can design all sequences using a tool like WSO2 Developer Studio, and store the sequence.xml file in the governance registry. The registry collection where sequences are stored is
customsequences, which is available by default in
apimgt governance registry location. The registry path is
/_system/governance/apimgt/customsequences. Store the
InSequence files in
apimgt/customsequences/in folder and the
OutSequence files in
apimgt/customsequences/out folder. For example, if you have an in sequence file as
testInSequence, you must save it in /_system/governance/apimgt/customsequences/in/testInSequence.xml and if you have an out sequence file as
testOutSequence, save it in
There are two ways to apply mediation extensions to messages:
- : Apply to all APIs
- : Apply only to an intended 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.
Creating global extensions
Given below is the naming pattern of a global extension sequence.
<DIRECTION> can be either
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). Shown below is an example synapse configuration of a global extension 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.
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.
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 given as AT.
To test the code in super-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, if you are using a standalone server. In multi-tenant mode, copy the file to the tenant's synapse sequence folder. For example, if tenant id is 1, then copy it to
The above sequence prints a log message on the console whenever the
TwitterSearch API is invoked.
Selecting predefined APIs from the UI
Alternatively to the above approach, you can also attach extension sequences 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 down to the Sequences section. There, you can select In/Out sequences for the API from the drop-down lists. For example,
To populate these drop-down lists, you must add mediation sequences as explained in the beginning.
Invoking the 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
<APIM_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.