The API Gateway has a default mediation flow, which is executed in each API invocation. You can do additional custom mediation for the messages in the API Gateway by extending their mediation flow. 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
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 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 <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 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 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 <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, a file with its synapse configuration gets created on the API Gateway. If you inspect the synapse configuration of an API, you will see a set of handlers 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 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.
Allowing publisher to select the predefined sequences
If we have custom sequences with the naming convention as described above we can execute them. But if we want to allow publisher to select the sequences, when he defines the API, now we can do that via publisher webapp.
User can design all sequences using Dev Studio or any other tool, and store the sequence.xml file in the governance registry. We have introduced a new collection called "customsequences" at apimgt governance registry location. Store the InSequence files at apimgt/customsequences/in folder
Eg: If you have a in sequence file named as "testInSequence", you need to save the file here;
/_system/governance/apimgt/customsequences/in/testInSequence.xml
Same like insequence, for Out Sequences, user need to create another folder called "out" parallel to "in" folder.
Eg: If you have a out sequence file named as "testOutSequence", you need to save the file here;
/_system/governance/apimgt/customsequences/out/testOutSequence.xml
After saving the files, these seuences will be visible at publisher webapp, when publisher try to create an API. User has to check the option at the UI to select a custom sequence for InFlow and OutFlow.
Those sequences will be renamed and deployed to synapse when we publish the API to gateway.