User Tools

Site Tools


en:public:developer:template_system:tags:api:json_response_format

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:

  <foo bar="baz" />
  {
   "foo": {"bar": "baz"}
  }

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:

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

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.

  <outer>
    <photo id="1" />
    <photo id="2" />
  </outer>
  {
   "outer": {
             "photos": [
                        {"id": "1"},
                        {"id": "2"}
                       ]
            }
  }

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:

 <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>

And the JSON equivilent would be:

  {
   "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"
           }
          ]
  }

In JavaScript, displaying the logs is then straight forward:

  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);
    }
  }
 

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:

  {
    "stat": "fail",
    "code": "97",
    "message": "Error message"
  }

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”,…});

en/public/developer/template_system/tags/api/json_response_format.txt · Last modified: 2013/03/08 12:48 by admin