Some useful tips when using Properties in Mediation Policies - WSO2 API Manager

You might already explored the use of Mediation Policies in WSO2 API Manager. Mediation Policies are used to perform various changes to the default request flow; may be adding a new header to the request before going to the backend, converting client’s JSON payload into XML before sending to the backend etc.

Here, I am going into those specific use cases in this post. I hope to write them in next few posts. Here, I am focusing more about using Properties effectively during mediation policies.

For example, to log the user who are calling the API, we can use the below property with the log mediator.

<log level="custom">
    <property name="endUser" scope="default" expression="$ctx:api.ut.userName"/>
</log>

Use the correct Scope when using properties

When reading/setting properties, several scopes are available to use:

1. Synapse (default): Properties used to get details of the API, pass data between different components of the request, response processes.
2. Axis2: These properties can be used to pass instructions to the underline Axis2 engine.
3. Transport: To read/write transport headers
4. Registry: To access data from in-built registry
5. System: To access the JVM’s system properties
6. Environment: To access environment variables

Make sure to always explicitly specify the scope when accessing a property. Otherwise, the runtime engine tries to search for the property in each of the above scopes looking for its availability until one is found. This can cause a big performance impact.

Several ways to access properties

There are Three ways to access properties.

1. Property Mediator.

Basic Syntax:

<property name="string" [action=set|remove] [type="string"]     (value="literal" | expression="xpath")
[scope=default|transport|axis2|registry]
</property>

Property mediator can be used to both read or write properties.

<property name="endUser" scope="default" value="john"/>
<property name="endUser" scope="default" expression="get-property('default', 'api.ut.userName')"/>
<property name="REST_URL_POST_FIX" scope="axis2" value="/res/1"/>
<property name="REST_URL_POST_FIX" scope="axis2" action="remove"/>

2. get-property XPath function

Basic Syntax:

get-property(String propertyName)
get-property(String scope, String propertyName)

Allowed scopes are: default, axis2,registry, transport, system, env

Example:

<property name="endUser" scope="default" expression="get-property('default', 'api.ut.userName')"/>

3. XPath variables

For some of the scopes, properties can be accessed using a shorter form called XPath variables.

Available variables: $ctx (default/Synapse Scope), $axis2 (Axis2 Scope), $trp (Transport Scope), $url (Access pre-defined params in the URL)

Example:

<property name="endUser" scope="default" expression="$ctx:api.ut.userName"/>

Properties you set in the inbound flow is available in the outbound flow

When we set a certain property in the request flow using a custom mediator (using default scope), we can access the same property in the response flow as well. This is useful to exchange certain things between a custom-in mediation policy and a custom-out mediation policy.

Some important properties available to use when writing policies

We’ll take the inbuilt Pizzashack API as the example for demonstrating this. The API is deployed and its /order/{orderId} resource was invoked with additional query parameters and with a valid access token.

GET https://localhost:8243/pizzashack/1.0.0/order/1?include=prize&trackingMode=true
Authorization: Bearer eyJ4NXQiOiJNell4TW1Ga09HWXdNV0kwWl...

Message In-bound Flow:

Below properties are available to use in your custom-in mediation policy.

Message out-bound Flow:

All the Properties specified above in Synapse scope are available here as well. In addition to them, below are available to use.

Let’s meet again with a post with some example use cases of using those properties.