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 their 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 /_system/governance/apimgt/customsequences/out/testOutSequence.xml.
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
...
Given below is the naming pattern of the sequence to follow when creating a global extension sequence.
...
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 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.
...
Given below is the naming pattern to follow when creating of a per-API extension sequence.
<API_NAME>:v<VERSION>--<DIRECTION>
Following 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.
| Code Block | ||
|---|---|---|
| ||
<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> |
| Info |
|---|
NOTE: The tenant username must be given as |
To test the code in super-tenant mode, copy it to an xml 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.
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 gets is created on the API Gateway. If you inspect the This synapse configuration of an API, you will see 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 determine determines what APIs need to must 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 section and provide the value top as follows:
...
For more information on Handlers, see Architecture Components.
Allowing publisher to select the predefined sequences
Publisher is allowed to select the predefined sequences, when he defines the API 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 registry collection to store the sequences file. For sequences, create "customsequences" collection at apimgt governance registry location. The registry path will be like " /_system/governance/apimgt/customsequences".
In the "customsequences" collection , user has to create two collections "in" and "out" for InSequences and OutSequences.
| Info | ||
|---|---|---|
| ||
If registry collection is not available, user has to create the collection prior to store the sequences. |
Store the InSequence files at apimgt/customsequences/in folder .
| Info | ||
|---|---|---|
| ||
If you have a in sequence file named as "testInSequence", you need to save the file in the following location ; /_system/governance/apimgt/customsequences/in/testInSequence.xml |
Store the OutSequence files at apimgt/customsequences/out folder .
| Info | ||
|---|---|---|
| ||
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 sequences 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 with the naming convention as described above and deployed to synapse when we publish the API to gateway.