Change the Default Mediation Flow of API Requests
The API Gateway has a default mediation flow for the API invocation requests that it receives. You can extend this default mediation flow to do additional custom mediation for the messages in the API Gateway. An extension is provided as a synapse mediation sequence. You design sequences using a tool like WSO2 Developer Studio and then upload the sequence via the APIM Perspective.
Tip: If you prefer not to use WSO2 Developer Studio to upload the sequence or want to engage a sequence to all APIs in the APIM at once, you can do so by creating a sequence manually and uploading it from the API Publisher or by saving the mediation sequence XML file in the file system. See Adding Mediation Extensions for details.
Let's see how to create a custom sequence using WSO2 Developer Studio and then deploy and use it in your APIs.
Log in to the API Publisher.
Click Add to create an API with the following information and then click Implement.
Field Sample value Name YahooWeather Context /weather Version 1.0 Resources URL pattern current/{country}/{zipcode} Request types GET method to return the current weather conditions of a zip code that belongs to a particular country
The
Implement
tab opens. Select Managed API, provide the information given in the table below and click Manage.Field Sample value Endpoint type HTTP endpoint Production endpoint You can find the Yahoo weather API's endpoint from https://developer.yahoo.com/weather/. Copy the part before the '?' sign to get this URL: https://query.yahooapis.com/v1/public/yql
To verify the URL, click the Test button next to it.
Sandbox endpoint https://query.yahooapis.com/v1/public/yql To verify the URL, click the Test button next to it. Click Manage to go to the
Manage
tab, provide the following information and click Save & Publish once you are done.Field Sample value Tier Availability Gold Keep the default values for the other attributes Download WSO2 Developer Studio (version 3.8.0 is used here) from http://wso2.com/products/developer-studio/ and open it by double clicking the
Eclipse.app
file inside the downloaded folder.- Click Window > Open Perspective > Other to open the Eclipse perspective selection window. Alternatively, click the Open Perspective icon shown below at the top right corner.
- On the dialog box that appears, click WSO2 APIManager and click OK.
- On the APIM perspective, click the Login icon as shown below.
- On the dialog box that appears, enter the URL, username and password of the Publisher server.
- On the tree view that appears, expand the folder structure of the existing API.
Right-click on the
in
sequence folder and click Create to create a newin
sequence.
This is because you want the custom sequence to be invoked in theIn
direction or the request path. If you want it to be involved in theOut
orFault
paths, select the respective folder undercustomsequences
.- Name the sequence
YahooWeatherSequence
. Your sequence now appears on the Developer Studio console. From under the Mediators section, drag and drop a Property mediator to your sequence and give the following values to the property mediator.
Property Name New Property New Property Name YQL Value Type Expression Value Expression For the XPath expression, we take a part of the query in the Yahoo API's endpoint (https://developer.yahoo.com/weather/) and concatenate the zip code and country to it using the synapse get-property XPath expression:
concat('?q=select%20*%20from%20weather.forecast%20where%20woeid%20in%20(select%20woeid%20from%20geo.places(1)%20where%20text%3D%22',syn:get-property('uri.var.zipcode'),',',syn:get-property('uri.var.country'),'%22)&format=json')
Similarly, add another property mediator with the following values. This is an HTTP transport property that appends its value to the address endpoint URL. Once you are done, save the sequence.
Property Name New Property New Property Name REST_URL_POSTFIX Value Type Expression Value Expression Set the value of the property mediator that you created earlier as get-property('YQL') Property Scope Axis2 - Save the sequence.
- Right-click on the sequence and click Commit File to push the changes to the Publisher server.
- Log back in to the API Publisher, select the API that you created earlier and click the Edit link right next to its name to go to the edit wizard.
Navigate to the API's Implement tab, select the Enable Message Mediation check box and select the sequence that you created for the
In
flow. Next, click Manage and Save & Publish the API again.Tip: It might take a few minutes for the sequence to be uploaded into the API Publisher. If it isn't there, please check again later.
- Open the API Store, subscribe to the API that you just published and generate the access tokens in order to invoke the API.
- Click the API Console tab of the API. It opens the integrated API Console using which you can invoke the API.
Give the following values for the parameters and invoke the API. You can also give any other value of your choice.
country usa
zipcode 95004 - Note the response that you get as a JSON object from Yahoo.
In this tutorial, you created a sequence to change the default mediation flow of API requests, deployed it in the API Gateway and invoked an API using the custom mediation flow.
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
Truobleshooting
Use the following sample sequence to handle faults, when an invalid JSON request is sent.
<?xml version="1.0" encoding="UTF8"?> <sequence xmlns="http://ws.apache.org/ns/synapse" name="<insequence_name>" onError="fault" > <log level="full"> <property name="MessageFlow" value="--------In sequence of the message flow-------"/> </log> </sequence>
<sequence xmlns="http://ws.apache.org/ns/synapse" name="fault" onError="faultSeq" > <log level="custom"> <property name="STATUS:" value="fault invoked" /> <property name="STATUS" value="Executing default 'fault' sequence" /> <property name="ERROR_CODE" expression="getproperty('ERROR_CODE')" /> <property name="ERROR_MESSAGE" expression="getproperty('ERROR_MESSAGE')" /> </log> <switch source="//fault/type........"> <case regex="invalid......">................</case> <default>...............</default> </switch> <class name="org.wso2.carbon.apimgt.usage.publisher.APIMgtFaultHandler" /> <property name="RESPONSE" value="true" /> <header name="To" action="remove" /> <property name="NO_ENTITY_BODY" scope="axis2" action="remove" /> ........................................................................................ <property name="XJWTAssertion" scope="transport" action="remove" /> <sequence key="_cors_request_handler_" /> <send /> </sequence>
<?xml version="1.0" encoding="UTF8"?> <sequence xmlns="http://ws.apache.org/ns/synapse" name="faultSeq" > <class name="org.wso2.carbon.samples.FaultErrorMediator"></class> <property description="" name="ContentType" scope="axis2" type="STRING" value="application/xml"/> <sequence key="fault"/> </sequence>
Add these error sequences using WSO2 Developer Studio, following the steps mentioned above.