This documentation is for WSO2 API Manager 1.8.0 View documentation for the latest release.
Page Comparison - Adding Mediation Extensions (v.6 vs v.7) - API Manager 1.8.0 - WSO2 Documentation

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: DOCUMENTATION-7722

...

Please do not use the API Manager's management console to create sequences as the functionality is not supported. You can design all sequences 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:

SequenceRegistry path
In/_system/governance/apimgt/customsequences/in
Out/_system/governance/apimgt/customsequences/out
Fault/_system/governance/apimgt/customsequences/fault

For example, if you have an in sequence file as testInSequence, you must save it in /_system/governance/apimgt/customsequences/in/testInSequence.xml.

There are two ways to apply mediation extensions to messages:

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.

Note

Please note that following mediators are not usable within custom sequences since they are not supported by API Gateway custom medications.

  • Call mediator in non-blocking mode
  • Send mediator

Creating

...

per-API extensions

...

Table of Contents

...

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

maxLevel

...

4
minLevel4

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:

SequenceRegistry path
in/_system/governance/apimgt/customsequences/in
out/_system/governance/apimgt/customsequences/out
fault/_system/governance/apimgt/customsequences/fault

For example, if you have an in sequence file, testInSequence, you must save it in the /_system/governance/apimgt/customsequences/in/testInSequence.xml file.

Once you create the XML file, upload it to the registry using the management console UI.

  1. Open the API-M management console (https://localhost:9443/carbon with admin/admin as the default credentials) and select Resources > Browse.
  2. Navigate to the /_system/governance/apimgt/customsequences registry location.
  3. 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,

Image Added

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 <API-M_HOME>/repository/deployment/server/synapse-configs/default/sequences directory.
  • 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 <API_Gateway>/repository/tenants/1/synapse-configs/default/sequences folder. 

In the naming pattern, the <DIRECTION> can be In or Out. When it is In, the extension is triggered on the in-flow (request path) . Similarly, when the direction of the sequence and when it 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 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.

Code Block
languagehtml/xml
titleGlobal Extension Sequence Example
<sequence xmlns="http://ws.apache.org/ns/synapse" name="WSO2AMadmin--ExtTwitterSearch:v1.0.0--In">
    <log level="custom">
        <property name="TRACE" value="GlobalAPI Mediation Extension"/>
    </log>
</sequence>

...

Info

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., global twittersearch_ext.xml) and save the file in the <APIM_HOME>it in the <API_Gateway>/repository/deployment/server/synapse-configs/default/sequences directory directory.

The above sequence prints a log message on the console on every API invocationwhenever the TwitterSearch API is invoked.

Creating

...

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

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

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 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 per-API global extension sequence. It is created for an API named admin--TwitterSearch with version 1.0.0.

...

An example synapse configuration of a global extension sequence is given below:

Code Block
languagehtml/xml
titleGlobal Extension Sequence Example
<sequence xmlns="http://ws.apache.org/ns/synapse" name="adminWSO2AM--TwitterSearch:v1.0.0Ext--In">
    <log level="custom">
        <property name="TRACE" value="APIGlobal Mediation Extension"/>
    </log>
</sequence>
Info

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.

To test the code in super-tenant mode, copy it to an XML file (e.g., twittersearchglobal_ext.xml) and save the file in the <APIMthe <API-M_HOME>/repository/deployment/server/synapse-configs/default/sequences directory, if you are in single-tenant mode. 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.  directory. The above sequence prints a log message on the console whenever the TwitterSearch API is invoked.

Alternatively, you can create the XML file and upload it to the registry using the management console UI.

  1. Open the APIM management console (https://localhost:9443/carbon with admin/admin as the default credentials) and select Resources -> Browse.
  2. Navigate to /_system/governance/apimgt/customsequences registry location.
  3. Click Add Resource link to upload the XML file.

Selecting predefined APIs from the UI

You can attach pre-defined 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 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,

Image Removed

To populate these drop-down lists, you must add mediation sequences as explained at the beginning.

Invoking the extension sequences

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:

Code Block
languagehtml/xml
titleAPI Configuration
<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 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 <APIMthe <API-M_HOME>/repository/conf/api-manager.xml file file, uncomment the the <ExtensionHandlerPosition> section  section and provide the value value top as  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 API Manager Components.