JSON (short for JavaScript Object Notation) is a text-based representation of structured data, and as such an alternative to XML (Extensible Markup Language). JSON’s primary claim to fame is that when working with JavaScript, it can easily be transformed into JavaScript objects; however in general it is programming language-independent and can be used as a general purpose approach for data exchange. It has become increasingly popular especially in the context of RESTful interfaces.
The VoiceObjects Connector object has added comprehensive support for RESTful interfaces with the past few releases, and with VoiceObjects 11.1 we now also provide a variety of convenience mechanisms for dealing with JSON markup – XML has always been supported as the “native” language.
Assume we have a RESTful backend that returns the following JSON structure encompassing a user’s fictitious contact details:
{ "person":
{ "lastName":"Smith",
"phoneNumber":12345,
"address":{"streetAddress":"21 2nd Street", "postalCode":10021, "state":"NY", "city":"New York"},
"age":25,
"firstName":"John"
}}
Further assume that for the purpose of our application, we would like to extract the user’s first and last name as well as the city he lives in. How best to do this?
In previous versions of VoiceObjects, the answer would likely have been to use a Script object. This, of course, still works – but in 11.1 there is a much simpler way since VoiceObjects now implicitly and automatically converts JSON results into XML, on which you can then utilize XPATH expressions in the Result Mapping portion of the Connector object.
In our example, VoiceObjects automatically converts the JSON return value into the following XML structure (see below for more details on the conversion):
<person>
<lastName>Smith</lastName>
<phoneNumber>12345</phoneNumber>
<address>
<streetAddress>21 2nd Street</streetAddress>
<postalCode>10021</postalCode>
<state>NY</state>
<city>New York</city>
</address>
<age>25</age>
<firstName>John</firstName>
</person>
So we can use a Result Mapping as shown in this screenshot to extract first name, last name, and city:
Since the conversion from JSON to XML is not a one-to-one mapping, some ground rules need to be defined for boundary cases. They are as follows:
- No XML attributes are used; everything is converted to elements.
- If the JSON structure does not provide a “natural” XML root element that wraps the structure, then a wrapping outer element <root> is added.
- If a list of items in JSON does not provide a “natural” wrapping XML element, then the wrapping element <array> is added.
- XML-specific characters such as ampersand (&) or brackets (<,>) are automatically masked.
A simple example incorporating these rules would be the JSON structure
[1, "2<3", "a&b"]
which gets translated into the XML
<root>
<array>1</array>
<array>2<3</array>
<array>a&b</array>
</root>
RESTful backend interfaces sometimes also allow you to to specify your preferred result format, e.g. XML or JSON. Often this is done by setting the “Accept” header of your request appropriately.
VoiceObjects 11.1 lets you to do this, too, by setting an entry in the Connector object’s Parameter Set using a notation of the form #HeaderName#. So if you want to set the “Accept” header to “application/json” to indicate that you prefer a JSON result structure, you would do this:
For the Result Mapping inside Connector objects, the conversion from JSON to XML is done automatically. Outside of Connector objects, it is also possible to manually convert between XML and JSON using the two new Expression functions XML2JSON() and JSON2XML(). This uses the same conversion as that for Result Mapping.
As always, we’re looking forward to your feedback, so do not hesitate to contact us with any questions or comments you may have!
RSS FEED