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 all sequences using a tool such as the WSO2 API Manager Tooling Plug-in and then store the sequence in the Gateway's registry. 

Let's see how to create a custom sequence using the WSO2 API Manager Tooling Plug-in and then deploy and use it in your APIs.

1. Log in to the API Publisher.

2. Click Add to create an API with the following information and then click Next: 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

   

3. The Implement tab opens. Select Managed API, provide the information given in the table below and click Manage.

   Field	Sample value
   Endpoint type	HTTP/REST 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.

   

4. Click Next: 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

   

5. Download and install the WSO2 API Manager Tooling Plug-in if you have not done so already. Open Eclipse by double clicking the Eclipse.app file inside the downloaded folder. 

6. 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.
   
7. On the dialog box that appears, click WSO2 APIManager and click OK.
   
8. On the APIM perspective, click the Login icon as shown below.
    
9. On the dialog box that appears, enter the URL, usernameand password of the Publisher server.
   
10. On the tree view that appears, expand the folder structure of the existing API.

11. Right-click on the in sequence folder and click Create to create a new in sequence.
    
    This is because you want the custom sequence to be invoked in the In direction or the request path. If you want it to be involved in the Out or Fault paths, select the respective folder under customsequences.

    Tip: If you prefer not to use the registry to upload the sequence or want to engage a sequence to all APIs in the APIM at once, you can do so by saving the mediation sequence XML file in the file system. See Adding Mediation Extensions for details.

12. Name the sequence YahooWeatherSequence.

13. 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. 

    The Property Mediator has no direct impact on the message, but rather on the message context flowing through Synapse. You can retrieve the properties set on a message later through the Synapse XPath Variables or the get-property() extension function. In this sequence, we are using two property mediators and set a Synapse XPath variable and a get-property() function to the two mediators respectively to retrive the properties setto the message context during the execution.

    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')
    Property Scope	Synapse Since this is a mediation level Property keep the Property Scope as Synapse. This is the default scope set when no Property Scope is defined.

    

14. 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	get-property('YQL')
    Property Scope	Axis2 Since this is a transport level property, set the Property Scope as Axis2.

    

15. Save the sequence.
16. Right-click on the sequence and click Commit File to push the changes to the Publisher server.
17. Log back in tothe 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. 
    

18. 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.

    

    When selecting a mediator, make sure that it is a non-blocking mediator as blocking mediators are not supported in API Gateway custom mediations. For more details, see Adding Mediation Extensions.

19. Open the API Store, subscribe to the API that you just published and generate the access tokens in order to invoke the API.
    
20. Click the API Console tab of the API. It opens the integrated API Console using which you can invoke the API.
    

21. 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

    

22. 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.