Page Comparison

...

Table of Contents

maxLevel	3

Also see the following sections in the WSO2 ESB documentation. WSO2 ESB is used to implement the API Gateway through which API messages are transformed:

JSON message builders and formatters

...

Code Block

language	html/xml

 <api name="admin--TOJSON" context="/tojson" version="1.0" version-type="url">
        <resource methods="POST GET DELETE OPTIONS PUT" url-mapping="/*">
            <inSequence>
                <property name="POST_TO_URI" value="true" scope="axis2"/>
                <filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
                    <then>
                        <send>
                            <endpoint name="admin--Test_APIproductionEndpoint_0">
                                <http uri-template="http://localhost:9767/services/StudentService">
                                    <timeout>
                                        <duration>30000</duration>
                                        <responseAction>fault</responseAction>
                                    </timeout>
                                    <suspendOnFailure>
                                        <errorCodes>-1</errorCodes>
                                        <initialDuration>0</initialDuration>
                                        <progressionFactor>1.0</progressionFactor>
                                        <maximumDuration>0</maximumDuration>
                                    </suspendOnFailure>
                                    <markForSuspension>
                                        <errorCodes>-1</errorCodes>
                                    </markForSuspension>
                                </http>
                            </endpoint>
                        </send>
                    </then>
                    <else>
                        <sequence key="_sandbox_key_error_"/>
                    </else>
                </filter>
            </inSequence>
            <outSequence>
                <property name="messageType" value="application/json" scope="axis2"/>
                <send/>
            </outSequence>
        </resource>
        <handlers>
            <handler class="org.wso2.carbon.apimgt.gateway.handlers.security.APIAuthenticationHandler"/>
            <handler class="org.wso2.carbon.apimgt.gateway.handlers.throttling.APIThrottleHandler">
                <property name="id" value="A"/>
                <property name="policyKey" value="gov:/apimgt/applicationdata/tiers.xml"/>
            </handler>
            <handler class="org.wso2.carbon.apimgt.usage.publisher.APIMgtUsageHandler"/>
            <handler class="org.wso2.carbon.apimgt.usage.publisher.APIMgtGoogleAnalyticsTrackingHandler"/>
            <handler class="org.wso2.carbon.apimgt.gateway.handlers.ext.APIManagerExtensionHandler"/>
        </handlers>
    </api>

Accessing content from JSON payloads

There are two ways to access the content of a JSON payload:

JSONPath expressions (with json-eval() method)
XPath expressions

JSONPath allows you to access fields of JSON payloads with faster results and less processing overhead. Although it is possible to evaluate XPath expressions on JSON payloads by assuming the XML representation of the JSON payload, we recommend that you use JSONPath to query JSON payloads. It is also possible to evaluate both JSONPath and XPath expressions on a payload (XML/JSON) at the same time.

You can use JSON path expressions with following mediators:

Mediator Usage References

Log

As a log property:

Code Block

language	html/xml

<log>
    <property name="location" 
              expression="json-eval($.coordinates.location[0].name)"/>
</log>

https://docs.wso2.org/display/ESB481/Log+Mediator

Property

As a standalone property:

Code Block

language	html/xml

<property name="location" 
              expression="json-eval($.coordinates.location[0].name)"/>

https://docs.wso2.org/display/ESB481/Property+Mediator

PayloadFactory

As the payload arguments:

Code Block

language	html/xml

<payloadFactory media-type="json">
    <format>{"RESPONSE":"$1"}</format>
    <args>
        <arg evaluator="json" expression="$.coordinates.location[0].name"/>
    </args>
</payloadFactory>

IMPORTANT: You MUST omit the json-eval() method within the payload arguments to evaluate JSON paths within the PayloadFactory mediator. Instead, you MUST select the correct expression evaluator (xml or json) for a given argument.

https://docs.wso2.org/display/ESB481/PayloadFactory+Mediator

Switch

As the switch source:

Code Block

language	html/xml

<switch source="json-eval($.coordinates.location[0].name)">

https://docs.wso2.org/display/ESB481/Switch+Mediator

Filter

As the filter source:

Code Block

language	html/xml

<filter source="json-eval($.coordinates.location[0].name)" 
        regex="Eiffel.*">

https://docs.wso2.org/display/ESB481/Filter+Mediator

JSON path syntax

Suppose we have the following payload:

Code Block

language	javascript

{ 
  "id": 12345,
  "id_str": "12345",
  "array": [ 1, 2, [ [], [{"inner_id": 6789}] ] ],
  "name": null,
  "object": {},
  "$schema_location": "unknown",
  "12X12": "image12x12.png"
}

The following table summarizes sample JSONPath expressions and their outputs:

Expression	Result
$.	{ "id":12345, "id_str":"12345", "array":[1, 2, [[],[{"inner_id":6789}]]], "name":null, "object":{}, "$schema_location":"unknown", "12X12":"image12x12.png"}
$.id	12345
$.name	null
$.object	{}
$.['$schema_location']	unknown
$.12X12	image12x12.png
$.array	[1, 2, [[],[{"inner_id":6789}]]]
$.array[2][1][0].inner_id	6789

You can learn more about JSONPath syntax here.

Logging JSON payloads

To log JSON payloads as JSON, use the Log mediator as shown below. The json-eval() method returns the java.lang.String representation of the existing JSON payload.

Code Block

language	html/xml

<log>
    <property name="JSON-Payload" expression="json-eval($.)"/>
</log>

To log JSON payloads as XML, use the Log mediator as shown below:

Code Block

language	html/xml

<log level="full"/>

For more information on logging, see Troubleshooting, debugging, and logging below.

Constructing and transforming JSON payloads

To construct and transform JSON payloads, you can use the PayloadFactory mediator or Script mediator as described in the rest of this section.

PayloadFactory mediator

The PayloadFactory mediator provides the simplest way to work with JSON payloads. For information on the mediator, see WSO2 ESB documentation: https://docs.wso2.org/display/ESB481/PayloadFactory+Mediator. Suppose we have a service that returns the following response for a search query:

Code Block

language	javascript

{
   "geometry":{
      "location":{
         "lat":-33.867260,
         "lng":151.1958130
      }
   },
   "icon":"bar-71.png",
   "id":"7eaf7",
   "name":"Biaggio Cafe",
   "opening_hours":{
      "open_now":true
   },
   "photos":[
      {
         "height":600,
         "html_attributions":[
         ],
         "photo_reference":"CoQBegAAAI",
         "width":900
      }
   ],
   "price_level":1,
   "reference":"CnRqAAAAtz",
   "types":[
      "bar",
      "restaurant",
      "food",
      "establishment"
   ],
   "vicinity":"48 Pirrama Road, Pyrmont"
}

We can create a proxy service that consumes the above response and creates a new response containing the location name and tags associated with the location based on several fields from the above response.

Code Block

language	html/xml
linenumbers	true

<proxy xmlns="http://ws.apache.org/ns/synapse"
     name="singleresponse"
     transports="https,http"
     statistics="disable"
     trace="disable"
     startOnLoad="true">
     <target>
         <outSequence>
             <payloadFactory media-type="json">
                 <format>{
                             "location_response" : {
                                 "name" : "$1",
                                 "tags" : $2
                         }}
                 </format>
                 <args>
                     <arg evaluator="json" expression="$.name"/>
                     <arg evaluator="json" expression="$.types"/>
                 </args>
             </payloadFactory>
             <send/>
         </outSequence>
         <endpoint>
             <address uri="http://localhost:82801/location"/>
         </endpoint>
     </target>
 <description/>
</proxy>

Use the following command to invoke this service:

Code Block

language	bash

curl -v -X GET "http://localhost:8280/services/singleresponse"

The response payload would look like this:

Code Block

language	javascript

{
   "location_response":{
      "name":"Biaggio Cafe",
      "tags":["bar", "restaurant", "food", "establishment"]
   }
}

Note the following aspects of the proxy service configuration:

We use the payloadFactory mediator to construct the new JSON payload.
The media-type attribute is set to json.
Because JSONPath expressions are used in arguments, the json evaluators are specified.

Configuring the payload format

The <format> section of the proxy service configuration defines the format of the response. Notice that in the example above, the name and tags field values are enclosed by double quotes ("), which creates a string value in the final response. If you do not use quotes, the value that gets assigned uses the real type evaluated by the expression (boolean, number, object, array, or null).

It is also possible to instruct the PayloadFactory mediator to load a payload format definition from the registry. This approach is particularly useful when using large/complex payload formats in the definitions. To load a format from the registry, click Pick From Registry instead of Define inline when defining the PayloadFactory mediator.

For example, suppose we have saved the following text content in the registry under the location conf:/repository/esb/transform. (The resource name is “transform”.)

Code Block

language	html/xml
linenumbers	true

{
    "location_response" : {
        "name" : "$1",
        "tags" : $2
    }
}

We can now modify the definition of the PayloadFactory mediator to use this format text saved as a registry resource as the payload format. The new configuration would look as follows (note that the <format> element now uses the key attribute to point to the registry resource key):

Code Block

language	html/xml

<payloadFactory media-type="json">
  <format key="conf:/repository/esb/transform"/>
  ... 
</payloadFactory>

Note
When saving format text for the PayloadFactory mediator as a registry resource, be sure to save it as text content with the “text/plain” media type.

Script mediator

The Script mediator (https://docs.wso2.org/display/ESB481/Script+Mediator) in JavaScript is useful when you need to create payloads that have recurring structures such as arrays of objects. The Script mediator defines the following important methods that can be used to manipulate payloads in many different ways:

getPayloadJSON
setPayloadJSON
getPayloadXML
setPayloadXML

By combining any of the setters with a getter, we can handle almost any type of content transformation. For example, by combining getPayloadXML and setPayloadJSON, we can easily implement an XML to JSON transformation scenario. In addition, we can perform various operations (such as deleting individual keys, modifying selected values, and inserting new objects) on JSON payloads to transform from one JSON format to another JSON format by using the getPayloadJSON and setPayloadJSON methods. Following is an example of a JSON to JSON transformation performed by the Script mediator.

Suppose a second service returns the following response:

Code Block

language	javascript

{
   "results" : [
      {
         "geometry" : {
            "location" : {
               "lat" : -33.867260,
               "lng" : 151.1958130
            }
         },
         "icon" : "bar-71.png",
         "id" : "7eaf7",
         "name" : "Biaggio Cafe",
         "opening_hours" : {
            "open_now" : true
         },
         "photos" : [
            {
               "height" : 600,
               "html_attributions" : [],
               "photo_reference" : "CoQBegAAAI",
               "width" : 900
            }
         ],
         "price_level" : 1,
         "reference" : "CnRqAAAAtz",
         "types" : [ "bar", "restaurant", "food", "establishment" ],
         "vicinity" : "48 Pirrama Road, Pyrmont"
      },
      {
         "geometry" : {
            "location" : {
               "lat" : -33.8668040,
               "lng" : 151.1955790
            }
         },
         "icon" : "generic_business-71.png",
         "id" : "3ef98",
         "name" : "Doltone House",
         "photos" : [
            {
               "height" : 600,
               "html_attributions" : [],
               "photo_reference" : "CqQBmgAAAL",
               "width" : 900
            }
         ],
         "reference" : "CnRrAAAAV",
         "types" : [ "food", "establishment" ],
         "vicinity" : "48 Pirrama Road, Pyrmont"
      }
   ],
   "status" : "OK"
}

The following proxy service shows how we can transform the above response using JavaScript with the Script mediator.

Code Block

language	html/xml
linenumbers	true

<proxy xmlns="http://ws.apache.org/ns/synapse"
       name="locations"
       transports="https,http"
       statistics="disable"
       trace="disable"
       startOnLoad="true">
   <target>
      <outSequence>
         <script language="js"
                 key="conf:/repository/esb/transform.js"
                 function="transform"/>
         <send/>
      </outSequence>
      <endpoint>
         <address uri="http://localhost:82801/locations"/>
      </endpoint>
   </target>
   <description/>
</proxy>

The registry resource transform.js contains the JavaScript function that performs the transformation:

Code Block

language	javascript
linenumbers	true

function transform(mc) {
    payload = mc.getPayloadJSON();
    results = payload.results;
    var response = new Array();
    for (i = 0; i < results.length; ++i) {
        location_object = results[i];
        l = new Object();
        l.name = location_object.name;
        l.tags = location_object.types;
        l.id = "ID:" + (location_object.id);
        response[i] = l;
    }
    mc.setPayloadJSON(response);
}

...

Code Block

language	bash

curl -v -X GET "http://ggrky:8280/services/locations"

The response payload would look like this:

Code Block

language	javascript

[
    {
        "id":"ID:7eaf7", 
        "tags":["bar", "restaurant", "food", "establishment"], 
        "name":"Biaggio Cafe"
    }, 
    {
       "id":"ID:3ef98", 
       "tags":["food", "establishment"], 
       "name":"Doltone House"
    }
]

If you want to get the response in XML instead of JSON, you would modify the out sequence by adding the Property mediator as follows:

Code Block

language	html/xml
linenumbers	true

<outSequence>
    <script language="js" 
            key="conf:/repository/esb/transform.js" 
            function="transform"/>
    <property name="messageType" value="application/xml" scope="axis2"/>
    <send/>
</outSequence>

The response will then look like this:

Code Block

language	html/xml

<jsonArray>
   <jsonElement>
      <id>ID:7eaf7</id>
      <tags>bar</tags>
      <tags>restaurant</tags>
      <tags>food</tags>
      <tags>establishment</tags>
      <name>Biaggio Cafe</name>
   </jsonElement>
   <jsonElement>
      <id>ID:3ef98</id>
      <tags>food</tags>
      <tags>establishment</tags>
      <name>Doltone House</name>
   </jsonElement>
</jsonArray>

If you are not getting the results you want when the Script mediator converts the JSON payload directly into XML, you can build the XML payload iteratively with the Script mediator as shown in the following script.

Code Block

language	javascript
linenumbers	true

function transformXML(mc) {
    payload = mc.getPayloadJSON();
    results = payload.results;
    var response = <locations/>;
    for (i = 0; i < results.length; ++i) {
        var elem = results[i];
        response.locations += <location>
            <id>{elem.id}</id>
            <name>{elem.name}</name>
            <tags>{elem.types}</tags>
        </location>
    }
    mc.setPayloadXML(response);
}

The response would now look like this:

Code Block

language	html/xml

<locations>
   <location>
      <id>7eaf7</id>
      <name>Biaggio Cafe</name>
      <tags>bar,restaurant,food,establishment</tags>
   </location>
   <location>
      <id>3ef98</id>
      <name>Doltone House</name>
      <tags>food,establishment</tags>
   </location>
</locations>

Finally, let's look at how you can perform delete, modify, and add field operations on JSON payloads with the Script mediator in JavaScript. Let's send the JSON message returned by the locations proxy service as the request for the following proxy service, transformjson:

Code Block

language	html/xml
linenumbers	true

<proxy xmlns="http://ws.apache.org/ns/synapse"
       name="transformjson"
       transports="https,http"
       statistics="disable"
       trace="disable"
       startOnLoad="true">
   <target>
      <inSequence>
         <script language="js"><![CDATA[
           payload = mc.getPayloadJSON();
           for (i = 0; i &lt; payload.length; ++i) {
               payload[i].id_str = payload[i].id;
               delete payload[i].id;
               payload[i].tags[payload[i].tags.length] = "pub";
           }
           mc.setPayloadJSON(payload);
         ]]></script>
         <log>
            <property name="JSON-Payload" expression="json-eval($.)"/>
         </log>
         <respond/>
      </inSequence>
   </target>
   <description/>
</proxy>

The proxy service will convert the request into the following format:

Code Block

language	javascript

[
   {
      "name":"Biaggio Cafe",
      "tags":["bar", "restaurant", "food", "establishment", "pub"],
      "id_str":"ID:7eaf7"
   },
   {
      "name":"Doltone House",
      "tags":["food", "establishment", "pub"],
      "id_str":"ID:3ef98"
   }
]

Note that the transformation (line 9 through 17) has added a new field id_str and removed the old field id from the request, and it has added a new tag pub to the existing tags list of the payload.

...

Troubleshooting, debugging, and logging

To assist with troubleshooting, you can enable debug logging at several stages of the mediation of a JSON payload by adding one or more of the following loggers to the <PRODUCT_HOME>/repository/conf/log4j.properties file and restarting the server.

Info
Be sure to turn off these loggers when running the server in a production environment, as logging every message will significantly reduce performance.

Following are the available loggers:

Message builders and formatters

log4j.logger.org.apache.synapse.commons.json.JsonStreamBuilder=DEBUG
log4j.logger.org.apache.synapse.commons.json.JsonStreamFormatter=DEBUG
log4j.logger.org.apache.synapse.commons.json.JsonBuilder=DEBUG
log4j.logger.org.apache.synapse.commons.json.JsonFormatter=DEBUG

JSON utility class

log4j.logger.org.apache.synapse.commons.json.JsonUtil=DEBUG

PayloadFactory mediator

log4j.logger.org.apache.synapse.mediators.transform.PayloadFactoryMediator=DEBUG

JSONPath evaluator

...

Versions Compared

Old Version 6

New Version Current

Key

JSON message builders and formatters

Accessing content from JSON payloads

JSON path syntax

Logging JSON payloads

Constructing and transforming JSON payloads

PayloadFactory mediator

Configuring the payload format

Script mediator

Troubleshooting, debugging, and logging

Message builders and formatters

JSON utility class

PayloadFactory mediator

JSONPath evaluator