JSON Encoding
Both the XML and JSON output from Dream services contain the same data; the only difference is in the format. The documentation on OpenGarden assumes XML output. In general you can assume these rules:
- There will be one top level object containing the response.
- Simple XML elements (elements that contain only content) become string/value pairs.
- Complex XML elements (elements that contain nested elements) become nested objects.
- Attributes become string/value pairs.
- If an element contains both content and attributes, the attributes become string/value pairs and the content becomes a string/value pair with the name "content."
- Repeated elements map onto arrays. The array is named after the element. The values of the array depend on the content of the repeated elements, that is, simple content becomes simple values, nested elements become objects. Note, however, that if a particular response that normally contains repeated element contains only one element you will not get an array of one element in the JSON output -- the element is treated as if it were a simple complex XML element. For repeated elements you should ensure you test for an array or a scalar value.
Getting JSON Output with "dream.out.format=jsonp"
By default all data exchanges with Dream services use XML. However, an XML response can be automatically converted to JSON by using the dream.out.format=jsonp parameter in the request URI:
http://dreamserver/stats/record/RESPONSE_TIME&dream.out.format=jsonp
Adding a Callback with "dream.out.pre=function"
In addition to the dream.out.format parameter, the URI can also contain a dream.out.pre parameter to prefix the JSON output with a function invocation. For example:
http://dreamserver/stats/record/RESPONSE_TIME&output=json&dream.out.pre=show_stats This request results in the following output:
show_stats( ...json output... );
Because JSON output is already JavaScript, it is automatically evaluated as a JavaScript object and you can access the elements inside it as if you had passed an object reference to your show_stats function.
The name of the callback function must be valid JavaScript identifier and thus can only contain upper and lowercase alphabetic characters (A-Z a-z), numbers (0-9), and underscore (_).
Sample Xml
GET http://dreamserver/stats/record/stat1<stat> <name>stat1</name> <source>http://localhost:8081/stats/record/stat1/</source> <service>http://localhost:8081/stats/</service> <min>0</min> <max>9.594</max> <avg>4.914</avg> <var>0.14535147392290246</var> <sum>49.14</sum> <count>10</count> <first>2006-05-17T00:26:36.6098976-07:00</first> <last>2006-05-17T00:42:27.4853392-07:00</last> <rate>95.08754416</rate> <ratevar>0.99909449928635941</ratevar> </stat>
Sample JSON
GET http://dreamserver/stats/record/stat...t.format=jsonp({
"stat" : {
"name" : "stat1",
"source" : "http://localhost:8081/stats/record/stat1/",
"service" : "http://localhost:8081/stats/",
"min" : "0",
"max" : "9.594",
"average" : "4.914",
"variance" : "0.14535147392290246",
"sum" : "49.14",
"count" : "10",
"first" : "2006-05-17T00:26:36.6098976-07:00",
"last" : "2006-05-17T00:42:27.4853392-07:00",
"rate" : "95.08754416",
"ratevar" : "0.99909449928635941"
}
}) Sample JSON with Callback
GET http://dreamserver/stats/record/stat...=ws_show_statsws_show_stats({
"stat" : {
"name" : "stat1",
"source" : "http://localhost:8081/stats/record/stat1/",
"service" : "http://localhost:8081/stats/",
"min" : "0",
"max" : "9.594",
"average" : "4.914",
"variance" : "0.14535147392290246",
"sum" : "49.14",
"count" : "10",
"first" : "2006-05-17T00:26:36.6098976-07:00",
"last" : "2006-05-17T00:42:27.4853392-07:00",
"rate" : "95.08754416",
"ratevar" : "0.99909449928635941"
}
}) Differences between "dream.out.format=jsonp" and "dream.out.format=json"
The JSON format can be output in two variations: with and without surrounding parenthesises. Since parenthesises have no impact on evaluation, they don't hurt when the desired output is only a JSON expression. However, when requiring a function call prefix, "jsonp" only requires the extra noun, whereas "json" needs the noun and the opening parenthesis in URL encoded format, plus a postfix closing the parenthesis.
The following two calls are equivalent:
GET http://dreamserver/stats/record/stat...=ws_show_stats
GET http://dreamserver/stats/recrod/stat...eam.out.post=)
Because "jsonp" is simpler to use and less error prone, it is generally preferred over the "json" output format, which remains supported for backwards compatibility.
