||
Skip to end of metadata
Go to start of metadata

This tutorial uses the WSO2 API Manager Tooling Plug-in.

The API Gateway has a default mediation flow, which you can extend by adding custom mediation sequences. You create a custom mediation sequence either manually or using a tool such as the WSO2 API Manager Tooling Plug-in, and then engage it per API or globally to all APIs of a specific tenant.  

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

  • Call mediator in non-blocking mode
  • Send mediator

Default mediation flow

You cannot dynamically construct the back-end endpoint of an API using the address endpoints in the WSO2 API Manager. To achieve the requirement of a dynamic endpoint, you can use the default endpoint instead. The default endpoint sends the message to the address specified in the To header. The To header can be constructed dynamically. For example,

In this example, you have constructed the service_ep property dynamically and assigned the value of this property to the To header. The default endpoint sends the message to the address specified in the To header, in this case, http://jsonplaceholder.typicode.com/posts/.

Adding a non-blocking send operation

In this example, the Send mediator in a proxy service using the VFS transport is transferring a file to a VFS endpoint. VFS is a non-blocking transport by default, which means a new thread is spawned for each outgoing message. The Property mediator added before the Send mediator removes the ClientAPINonBlocking property from the message to perform the mediation in a single thread. This is required when the file being transferred is large and you want to avoid out-of-memory failures.

Creating per-API extensions

Create and upload using the WSO2 API Manager Tooling Plug-in

The recommended way to engage a mediation extension sequence per API is to create a custom sequence using the WSO2 API Manager Tooling Plug-in, upload it via its APIM Perspective and then engage it using the API Publisher. The following tutorial demonstrates how to do this: Change the Default Mediation Flow of API Requests.

Create and upload manually in the API Publisher

You can also create a mediation sequence manually and upload it from the API Publisher itself. For instance, you can copy the above default mediation flow content into an XML file. In the Implement tab of the API, select the Enable Message Mediation check box and click the Upload In Flow or Upload Out Flow field (for the example above, it needs to be uploaded to the In flow). Once the file is uploaded, save and publish the API. When you invoke the API, the request is sent to the endpoint referred to in the To header.

Create manually and save in the file system

Alternatively, 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 <APIM_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) 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.

You can copy this content into an XML file (e.g., twittersearch_ext.xml) and save it in the <API_Gateway>/repository/deployment/server/synapse-configs/default/sequences directory.

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 with the naming pattern WSO2AM--Ext--<DIRECTION> and save it in the <APIM_HOME>/repository/deployment/server/synapse-configs/default/sequences directory.

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

This custom sequence assigns the value of your basic authentication to Authorization header.

You can copy this content into an XML file (e.g., global_ext.xml) and save it in the <API_Gateway>/repository/deployment/server/synapse-configs/default/sequences directory.

When you invoke your REST API via a REST Client, configure that client to have a custom header (Authentication) for your basic authentication credential and configure the Authorization header to contain the bearer token for the API. When you  send the Authentication and Authorization headers, the Gateway drops the Authorization header, converts the Authentication to Authorization headers and sends to the backend.

  • No labels