====== 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 [[http://www.json.org]].
 
To return an API response in JSON format, send a parameter "**output_format**" in the 
request with a value of "json".

===== Object Representation =====

Some simple rules are used when converting REST XML into JSON objects. 
Some examples illustrate this best. A single tag will be translated to JSON as follows:

<code xml>
  <foo bar="baz" />
</code>

<code javascript>
  {
   "foo": {"bar": "baz"}
  }
</code>

Each element is represented by a JSON object. Element attributes are represented by an object member 
with a string value. Child elements are represented by an object member with an object value:

<code xml>
  <foo bar="baz">
    <woo>
      <yay>hoopla</yay>
    </woo>  
  </foo>
</code>

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


For repeated elements (such as the <photo> element when fetching a list of photos), an array is 
used as the object member value (the member key represents the element name). 
Each value in the array is then an object representing a child element.

<code xml>
  <outer>
    <photo id="1" />
    <photo id="2" />
  </outer>
</code>

<code javascript>
  {
   "outer": {
             "photos": [
                        {"id": "1"},
                        {"id": "2"}
                       ]
            }
  }
</code>

===== Successful Responses =====

When a request is successful, the following JSON is returned:
{stat":"ok",...}

The single object passed in the function call represents the REST outer <rsp> element. 
The root element of the REST response is then a member of this object (the stat param also is - 
check this to see if the call was successful). For instance, get_wwwfile_logs has a 
documented response as follows:

<code xml>

 <rsp stat="ok">
   <log>
     <revision>7689</revision>
     <author>nik</author>
     <date>2/22/2013 1:10:45 PM</date>
   </log>
   <log>
     <revision>7658</revision>
     <author>www.arkadia.com</author>
     <date>2/21/2013 9:07:25 AM</date>
   </log>
 </rsp>

</code>

And the JSON equivilent would be:

<code javascript>

  {
   "stat":"ok",
   "logs":[
           {
            "revision":"7689",
            "author":"nik",
            "date":"2/22/2013 1:10:45 PM"
           },
           {
            "revision":"7658",
            "author":"www.arkadia.com",
            "date":"2/21/2013 9:07:25 AM"
           }
          ]
  }

</code>

In JavaScript, displaying the logs is then straight forward:

<code javascript>
  
  function showLogs(rsp){

    if (rsp.stat != "ok"){
      // something broke!
      return;
    }

    for (var i=0; i<rsp.logs.length; i++){
      var div = document.createElement('div');
      var txt = document.createTextNode(rsp.logs[i].author);
      div.appendChild(txt);
      document.body.appendChild(div);
    }
  }
  
</code>

===== Failure Responses =====

Failure responses will return a different JSON object. 
The object is not structured like the REST failure responses - 
instead it's simplified for JSON. For example:

<code javascript>
  {
    "stat": "fail",
    "code": "97",
    "message": "Error message"
  }
</code>

From JavaScript, you can check rsp.stat for failure, and then read the 
error from rsp.code and rsp.message.

===== Callback Function =====

To define your own callback function name, add the parameter **jsoncallback** with your desired name as 
the value.

no jsoncallback	-> {"stat":"ok",...}\\
jsoncallback=wooYay -> wooYay({"stat":"ok",...});