Sending JSON objects to RESTful Web Service APIs using the Web Service Connector Tool

Introduction

JavaScript Object Notation (JSON) is a lightweight data interchange format that is often used alongside or in preference to XML in RESTful web services. Unlike XML, JSON data does not typically conform to any strictly-defined schema; rather, the expected object format is conveyed to the applications programmer through documentation alone.

Many web service operations, specifically those using the POST or PUT HTTP commands, require a JSON object to be sent to the server describing the item to be created (for POST operations) or updated (for PUT operations). To determine the format of the required JSON object, you should refer to the web service documentation. When describing the object, it is only necessary to include those fields which are either compulsory or which you desire to make available in your Tasks.

As the Web Service Connector Tool is designed to require well-defined data in order to be able to receive data from and provide data to other Tools, it is necessary to provide a valid XML schema defining the format of any JSON objects which are to be provided as the input of a web service operation.

Inferring the schema from an exemplar input object

The easiest way to provide a schema for the input object is to write a sample input object in XML format and have the Web Service Connector Tool infer the schema from that object. This is best illustrated through an example.

{‘ticket’:{‘subject’:’TaskCentre’,’description’:’Trying to connect to the Zendesk web service’,’tags’:[‘taskcentre’,’zendesk’,’web service’]}}

The above JSON object translates to the below XML object:

<ticket>
  <subject> TaskCentre</subject>
  <description>Trying to connect to the Zendesk web service</description>
  <tags_list>
    <tag>taskcentre</tag>
    <tag>zendesk</tag>
    <tag> web service</tag>
  </tags_list>
</ticket>

The translation is mostly straightforward but there is one important point to note: the XML you write should be in the format required by your VBScript XML to JSON conversion functions (see below). The sample functions included at the bottom of this article require any XML element which is to be translated into a JSON array, denoted by enclosure within [] instead of {}, to have its name suffixed with “_list”.

Zendesk10

Once you have entered the exemplar object, click on the “Infer schema from XML” button to automatically generate a schema for the input object:
Zendesk11

Defining the XML to JSON conversion functions

Because the Web Service Connector Tool produces XML input by default, you need to define VBScript functions that convert the XML input into JSON and add them on the Advanced tab of the web service configuration dialog. Sample scripts can be found at the bottom of this article.
Zendesk12

Using the XML to JSON conversion functions

To use the functions defined in the previous step to convert the XML input into JSON format, you must tick the “Write Custom Message Body” box on the “Message Body” tab of the “Advanced HTTP Message” dialog seen previously, and specify the name of your XML to JSON conversion script (explained earlier in this article) in the following format: {=SCRIPTNAME(ThisOperation.XML)}.
Zendesk13

Sample XML to JSON conversion functions

IMPORTANT: This code listing comes without guarantee and is to be used at your own risk.

Function XML2JSON(ByVal xml)

     'Create the COM object
     Dim doc
     Set doc = CreateObject("Msxml2.DOMDocument.3.0")

     'Load the XML document and wait until it's ready
     doc.async = False
     doc.loadXML(xml)

     'Get the root element of the document
     Dim root
     Set root = doc.documentElement

     'Start calling the recursive conversion function at the root element
     Dim outStr
     outStr = XML2JSON_Recurse(root, False)
     XML2JSON = outStr

End Function

Function XML2JSON_Recurse(ByVal node, ByVal isAnonymous)

     nodeString = ""

     'If the node has no children, then it contains the empty string
     If Not node.hasChildNodes() Then

          'Write a key-value pair unless this node is part of an array, in which case just write the empty string
          If isAnonymous = False Then
               nodeString = """" & node.baseName & """:"""""
          Else
               nodeString = """"""
          End If

     'If the node has only one child and no grandchildren, then its child is a leaf containing text
     ElseIf node.firstChild Is node.lastChild And Not node.firstChild.hasChildNodes() Then

     'Write a key-value pair unless this node is part of an array, in which case just write the text value
     If isAnonymous = False Then
          nodeString = """" & node.baseName & """:""" & node.text & """"
     Else
          nodeString = """" & node.text & """"
     End If

Else

     Dim isArray
     isArray = False

     'If this node's name ends in "_list", then it's an array rather than an object
     If Right(node.baseName, 5) = "_list" Then
          isArray = True
     End If

     'Recurse on each of the node's children, passing them the value of is Array as their is Anonymous parameter
     For Each child In node.childNodes
          nodeString = nodeString & XML2JSON_Recurse(child, isArray) & ","
     Next

     'Get rid of the final comma from the list of children
     nodeString = Left(nodeString, Len(nodeString) - 1)

     'Enclose the list in square or curly brackets (depending on isArray)
     If isArray = True Then
          nodeString = "[" & nodeString & "]"
     Else
          nodeString = "{" & nodeString & "}"
     End If

     'If this node is not an item in an array and is not the root node, prepend its name to create a key-value pair
     If isAnonymous = False Then
          If isArray = True Then
               nodeString = """" & Left(node.baseName, Len(node.baseName) - 5) & """:" & nodeString
     Else
          If Not node.baseName = "root" Then
               nodeString = """" & node.baseName & """:" & nodeString
               End If
          End If
     End If

End If

XML2JSON_Recurse = nodeString

End Function