JSON Response

JSON Response Format

JSON, or JavaScript Object Notation, is a simple machine-readable data-interchange format, which makes constructing API applications in JavaScript easy (though it can be used from other languages too!). For more information about JSON, visit json.org.

To return an API response in JSON format, send a parameter "format" in the request with a value of "json".

Object Representation

Some simple rules are used when converting flickr REST XML into JSON objects.

For the most part the JSON response is a direct translation from the XML response. Where it made sense, XML-specific nodes were left out. For example, when a JSON Array is returned, the JSON response does not contain the "num-results" field since this value is available as a direct property on the array.

IMPORTANT: The one major difference is all xml nodes that were named with a hyphon, follow standard javascript camel casing for their JSON counterparts. For example, the xml node "uuid-list" is a JSON property named "uuidList"

Some examples illustrate this best. A single tag will be translated to JSON as follows:

<foo bar="baz" />
<foo bar="baz" />
{   
     "foo" :  {
           "bar": "baz"
     }
}
{
	"foo": {
		"bar": "baz"
	}
}
Each element is represented by a JSON object. Element attributes are represented by an object member with the correct data type (string, boolean or int). 
Child elements are represented by an object member with an object value 
<foo bar="baz">
 <woo  yay="hoopla" />
</foo>

{
 "foo": {
 "bar": "baz", 
 "woo": {
 "yay": "hoopla"
 }
 }
}
<foo bar="baz">
	<woo yay="hoopla" />
</foo>
{
	"foo": {
		"bar": "baz",
		"woo": {
			"yay": "hoopla"
		}
	}
}

Element text nodes are represented by the node itself.

<foo>text here!</foo>
{
 "foo" : "text here!"
}
{
    "foo": "text here!"
}
Repeated elements use an array as the object member value (the member key represents the element name) 
<uuid-list>
 <uuid date-received="20081204000000" 
 subject="Dell Days of Deals Begins Today: Up to $315 off Select Systems" 
 from-domain="Dell Direct <dell@dellhome.usa.dell.com>">e79a06b0-d4d5-4700-8ea2-9c01c69de07</uuid>
 <uuid>same</uuid>
</uuid-list>

"uuidList" : [
 { 
 "uuid" : "e79a06b0-d4d5-4700-8ea2-9c01c69de07",
 "dateReceived" : "20081012000000",
 "subject" : "subject goes here"
 },
 {
 ...item 2... etc.
 }
 ]
<uuid-list>
    <uuid date-received="20081204000000" subject="Dell Days of Deals Begins Today: Up to $315 off Select Systems" from-domain="Dell Direct <dell@dellhome.usa.dell.com>">e79a06b0-d4d5-4700-8ea2-9c01c69de07b
    </uuid>
</uuid-list>
         "uuidList":[
            {
               "uuid":"929e8038-674a-40de-842d-2f696ad04852",
               "dateReceived":"20081012000000",
               "subject":"\"George Sand, Some Aspects of Her Life and Writing\" for Sunday October 12, 2008",
               "fromDomain":"ArcaMax <ezines@arcamax.com>"
            }

JSON Response

By default, the API service will return JSON data. In general, this will not be useful to external callers of the API and you will need to use a JSONP response instead.

To specify a JSONP response simply append a second parameter to the original request callback=<your-callback-name> and the resulting JSON will automatically be wrapped around your specified Javascript callback.

The JSON response will always contain the object response as its wrapper object, along with some basic information about the response: status, isSuccess, format, and version. The actual API result object is then contained within an inner-object, for example, the searchResults object. This hierarchy mimics the XML hierarchy.

An example illustrating this concept is below.

{
   "response":{
      "status":"success",
      "isSuccess":true,
      "format":"json",
      "version":"2.0",
      "searchResults":{
         "uuidRequestUrl":"http://cta-vn7-ny1.corp/ea3-api/service/2.0.0/rest/api.service.email?method=getEmails&uuid={uuid}&include-all=1&per_page=25",
         "uuidList":[
            {
               "uuid":"929e8038-674a-40de-842d-2f696ad04852",
               "dateReceived":"20081012000000",
               "subject":"\"George Sand, Some Aspects of Her Life and Writing\" for Sunday October 12, 2008",
               "fromDomain":"ArcaMax <ezines@arcamax.com>"
            },
            {
               "uuid":"8c83c196-2a44-4eea-9953-a78c5755f3e0",
               "dateReceived":"20081010000000",
               "subject":"\"Ten Great Religions, An Essay in Comparative Theology\" for Friday October 10, 2008",
               "fromDomain":"ArcaMax <ezines@arcamax.com>"
            }
         ]
      }
   }
}

In Javascript, displaying the results of this call is then straightforward:

function callbackFunction(Result)
{
    alert(Result.response.searchResults.uuidList.length) ;
}

The easiest way to get a feel for our the JSON responses work is to simply make a call and view the resulting responses.