Try WSO2 Cloud for Free
Sign in

All docs This doc

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

The diagram below shows how this fits into an API call as a custom sequence.


Image RemovedImage Added
 

Convert a JSON message to XML

...

The diagram below shows how this fits into an API call as a custom sequence.


Image RemovedImage Added 

Extracting, transforming or replacing the contents of a message

...

The diagram below shows how this sequence fits in to the Out flow.


Image RemovedImage Added 
 

Manipulating a JSON message

...

The diagram below shows how this sequence fits in to the Out flow.


Image RemovedImage Added 

Adding headers

You can add custom headers to your sequences.

Table of Contents
maxLevel4
minLevel4
includeheader

Adding a custom header

...

 

Image Added

Headers are added to the sequence using the header mediator. You can set a name for the header and the scope as transport, as shown in the example below.

...

Passing an authorization header to your backend

...


Image Added 

You cannot directly create an authorization header with the name Authorization, in the API Cloud as the keyword Authorization is a reserved header name. The following is an alternative to add a header with this name. 

...

Code Block
<sequence xmlns="http://ws.apache.org/ns/synapse" name="authorization_header_exchange">
    <property name="X-Authorization" expression="get-property("'transport', 'X-Authorization')" scope="default" type="STRING"/>
    <property name="Authorization" expression="get-property('X-Authorization')" scope="transport" type="STRING" description=""/>
    <property name="X-Authorization" scope="transport" action="remove"/>
</sequence>

...

Filtering messages using a single condition

...


Image Added 

The Filter Mediator can be used to filter messages based on an XPath, JSONPath or a regular expression. If the test succeeds, the Filter mediator executes other mediators enclosed in the sequence. This acts as an if-else condition in java.

...

Using custom sequences, you can evaluate a value passed through the API or check against a series of multiple conditions and then execute the relevant logic. This custom mediation behaves in the same way as a switch statement in java. This string is matched against the regular expression in each switch case mediator, in the specified order. If a matching case is found, it will be executed, and the remaining switch case mediators are not processed. If none of the case statements are matching, and a default case is specified, the default will be executed.

Image Removed
Image Added 
 

Code Block
titleSyntax
<switch source="[XPath|json-eval(JSON Path)]">
   <case regex="string">
     mediator+
   </case>+
   <default>
     mediator+
   </default>?
</switch>

...

You can route to different backends based on the resource which the APIs is invoked with. The logic being applied is similar to the Filtering based on a series of conditions.


Image RemovedImage Added 
 

In this example we set backend endpoints based on the resource of the API invocation. Save the following code as an xml file. For instructions on adding this custom sequence to your API, see Add a Custom Sequence to your API. The steps are explained within the comments.

...

You can route you API to different endpoints based on an incoming header. 


Image RemovedImage Added 
 

This example shows how to create a single API and call multiple endpoints based on a version header passed in the request. You do not need to create an API for each backend endpoint version. You can easily use a custom sequence for the API to route to the required destination. The sample sequence is given below. Save the following code as an xml file. For instructions on adding this custom sequence to your API, see Add a Custom Sequence to your API.

...

Code Block
titleSyntax
<sequence xmlns="http://ws.apache.org/ns/synapse" name="property_sequence"> 
           	<property name="ContentType" value="text/xml" scope="axis2"/>                   
</sequence>

...

Code Block
titleSyntax
<sequence xmlns="http://ws.apache.org/ns/synapse" name="property_sequence"> 
           	<property name="messageType" value="text/xml" scope="axis2"/>                   
</sequence>

...

Code Block
titleSyntax
<sequence xmlns="http://ws.apache.org/ns/synapse" name="property_sequence"> 
	<property name="preserveProcessedHeaders" value="true" scope="default"/>
</sequence>

...

Code Block
titleSyntax
<sequence xmlns="http://ws.apache.org/ns/synapse" name="no_body_for_post_sequence"> 
	<property name="NO_ENTITY_BODY" action="remove" scope="axis2"/>
</sequence>

...

Code Block
titleSyntax
<sequence xmlns="http://ws.apache.org/ns/synapse" name="status_code_property_sequence"> 
	<property name="HTTP_SC" value="500" scope="axis2"/>
</sequence>

...


Code Block
titleSyntax
<sequence xmlns="http://ws.apache.org/ns/synapse" name="api_info_sequence"> 
	<log level="custom">  
		<property name="ApiName" scope="transport" expression="$ctx:API_NAME"/>
	</log>  
</sequence>

Reading path and query parameters inside the sequence

You can read your input parameters to your API using custom sequences.

Info
titleDifference between the path and query parameter

Path parameters are the parameters which are provided inline in the request URL. Query parameters are passed after a “?” character and concatenated with an “&” operand.
Image Removed

Image Added

Code Block
titleSyntax
<sequence xmlns="http://ws.apache.org/ns/synapse" name="api_info_sequence"> 
	<log level="custom">  
		<!-- Retrieving the path parameter-->
		<property name="countryCode" scope="transport" expression="uri.var.code"/>    
		<!-- Retrieving the query parameter-->
		<property name="id" scope="transport" expression="query.param.id"/>                           
	</log>  
</sequence>

Moving query parameters to the REST path

Your API backend often does not match the desired frontend representation. For example, it might have extra parameters (such as API keys) that you do not want to expose and have some query parameters that you now want to just include in the REST path. You might want to do a transformation like shown in the diagram below. To do this, you need to retrieve the parameter useful-param from the end user and then add it to the URL.

Image Modified

For a similar usecase, see this blog post.


Image RemovedImage Added 
 

In this example, the original request which we make through our WSO2 gateway with be in the following format. 

Code Block
https://gateway.api.cloud.wso2.com/t/wso2cloud/resource?useful-param=foo&aux=bar

When we map it to the backend which we have defined the request will be sent as follows.

Code Block
https://new.api/foo?useful-param=foo&aux=bar

Since what we really need to send to the backend is https://new.api/foo and we need to remove of the query parameters which are appended with the request URI defined in the original request. We need to add a sequence which drop the original request parameters from the request.The REST_URI_POSTFIX property removes the parameters in the request. Save the following code as an xml file. For instructions on adding this custom sequence to your API, see Add a Custom Sequence to your API.

Code Block
titleSyntax
<sequence xmlns="http://ws.apache.org/ns/synapse" name="drop_uri_sequence" >
	<property name="REST_URL_POSTFIX" scope="axis2" action="remove"/>
</sequence>

Disable chunking

Some back-end servers does do not accept chunked content. You need to disable chunking of the API requests made through the API Cloud. Save the following code as an xml file. For instructions on adding this custom sequence to your API, see Add a Custom Sequence to your API.

Code Block
titleSyntax
<?xml version="1.0" encoding="UTF-8"?>
<sequence xmlns="http://ws.apache.org/ns/synapse"           name="disable-chunking">
        	<property name="DISABLE_CHUNKING" value="true" scope="axis2" />
</sequence>

Debugging your requests

When making API requests it may be required to log certain attributes in the API request to verify the correctness of the requests. You can do this using the log mediator. This will log specific information which is requested through the sequence to the live log viewer.

There are four main levels of logging in the API Cloud

  • Full: If this is selected, all the standard headers logged at the Simple level as well as the full payload of the message will be logged. This log level causes the message content to be parsed and hence incurs a performance overhead.

  • Simple: If this is selected, the standard headers (i.e. To, From, WSAction, SOAPAction, ReplyTo, and MessageID) will be logged.

  • Headers: If this is selected, all the SOAP header blocks are logged.

  • Custom: If this is selected, only the properties added to the Log mediator configuration will be logged.

Code Block
titleSyntax of log mediator
<log [level="string"] [separator="string"]>
   <property name="string" (value="literal" | expression="[XPath|json-eval(JSON Path)]")/>*
</log>

See Retrieving information about an API call for a list of details regarding API calls.

Debugging requests
Code Block
titleSyntax
<?xml version="1.0" encoding="UTF-8"?>
<sequence name="debug_in_flow" xmlns="http://ws.apache.org/ns/synapse">
             <!-- All the standard headers as well as the full payload of the message will be logged -->
 	 <log level="full" />
	 <log level="custom">
                       <!-- Logs the host -->
	 	<property name="Host" expression="get-property('transport', 'Host')"/>
                        <!-- Logs the context of the API -->
		<property name="Context" expression="get-property('To')"/>
                       <!-- Logs the HTTP Method used for invoking the API -->
		<property name="HTTP_METHOD" expression="get-property('axis2', 'HTTP_METHOD')"/>
                        <!-- logs the request URI-->
		<property name="Resource" expression="$axis2:REST_URL_POSTFIX"/>
                       <!-- Logs the origin of the request -->
		<property name="Origin" expression="get-property('transport', 'Origin')"/>
                        <!-- Logs the content type of the request -->
		<property name="Content-Type" expression="get-property('transport', 'Content-Type')"/>
	 </log>

</sequence>
Tip

The following sequence is available in WSO2 API Cloud by default. See Add a Custom Sequence to your API for instructions on adding this to your API.

  • In Flow - debug_in_flow
Debugging responses
Code Block
titleSyntax
<?xml version="1.0" encoding="UTF-8"?>
<sequence name="debug_out_flow" xmlns="http://ws.apache.org/ns/synapse">
               <!-- All the standard headers as well as the full payload of the message will be logged -->
	<log level="full" />
	<log level="custom">
		<property name="EndPoint" expression="get-property('ENDPOINT_PREFIX')"/>
		<property name="Content-Type" expression="get-property('transport', 'Content-Type')"/>
	</log>
</sequence>


Tip

The following sequence is available in WSO2 API Cloud by default. See Add a Custom Sequence to your API for instructions on adding this to your API.

  • Out Flow - debug_out_flow

Service Chaining with API Cloud

If you need to invoke multiple other endpoints in order to get data to make the actual request of the API then you need to use a concept of service chaining. This sequence can be used if you need the response of calling one service to be used as the input to call the other service.

In this example we get the country name from the user and pass is to a backend to display the statistics for that country. The statistics backend requires the country ID to be passed and not the country name. The country ID which maps to the input country name should be obtained from an intermediate service.

Image Removed


Image Added 
 

Expand
titleExpand to see the description of the numbered steps in the diagram.
  • Request a-1 -> The API Consumer application makes a request to the API with a parameter names country.
  • Request b -> The request is received at the in flow custom mediation of the API and then it makes a call to an intermediate service to get the country details. Within the sequence a request is made to the endpoint passing the country name which we received as the input. http://countries.com/getCountry/us
  • Response b -> It returns the country details of the above endpoint back into the in flow custom mediation sequence along with the country id which is needed for the actual backend call.
  • Request a-2 -> This takes the response b as the input parameter to the actual backend which returns the stats of the country. This response is sent back to the user.

If you have a similar service chaining requirement with WSO2 API Cloud please contact our support team on cloud@wso2.com for us to provide you the steps and assist you with this usecase.

...