Differences

This shows you the differences between two versions of the page.

--- en:public:developer:template_system:tags:api:json_response_format [2013/03/08 11:31]
admin created
+++ en:public:developer:template_system:tags:api:json_response_format [2013/03/08 12:48] (current)
admin [Callback Function]
@@ Line 6: / Line 6: @@
 about JSON, visit [[http://www.json.org]].
-To return an API response in JSON format, send a parameter "format" in the request with a value of "json".
+To return an API response in JSON format, send a parameter "**output_format**" in the
+request with a value of "json".
-Object Representation
+===== Object Representation =====
-Some simple rules are used when converting flickr REST XML into JSON objects. Some examples illustrate this best. A single tag will be translated to JSON as follows:
+Some simple rules are used when converting REST XML into JSON objects.
-<foo bar="baz" />{
+Some examples illustrate this best. A single tag will be translated to JSON as follows:
-	"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:
+<code xml>
-<foo bar="baz">
+  <foo bar="baz" />
-	<woo yay="hoopla" />
+</code>
-</foo>{
-	"foo": {
-		"bar": "baz",
-		"woo": {
-			"yay": "hoopla"
-		}
-	}
-}
- Element text nodes are represented as if they were an attribute, using the special name "_content":
+<code javascript>
-<foo>text here!</foo>{
+  {
-	"foo": {
+   "foo": {"bar": "baz"}
-		"_content": "text here!"
+  }
-	}
+</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.
+Each element is represented by a JSON object. Element attributes are represented by an object member
-<outer>
+with a string value. Child elements are represented by an object member with an object value:
-	<photo id="1" />
-	<photo id="2" />
-</outer>{
-	"outer": {
-		"photo": [
-			{
-				"id": "1"
-			},
-			{
-				"id": "2"
-			}
-		]
-	}
-}
- Successful Responses
+<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:
-jsonFlickrApi({...});
+{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>;
- 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, flickr.blogs.getList has a documented response as follows:
+And the JSON equivilent would be:
- <blogs>
-	<blog id="73" name="Bloxus test" needspassword="0"
-		url="http://remote.bloxus.com/" />
-	<blog id="74" name="Manila Test" needspassword="1"
-		url="http://flickrtest1.userland.com/" />
-</blogs>
- And the Flickr JSON equivilent would be:
+&lt;code javascript&gt;
-jsonFlickrApi({
-	&quot;stat&quot;: "ok",
-	"blogs": {
-		"blog": [
-			{
-				"id"		: "73",
-				"name"		: "Bloxus test",
-				"needspassword"	: "0",
-				"url"		: "http://remote.bloxus.com/"
-			},
-			{
-				"id"		: "74",
-				"name"		: "Manila Test",
-				"needspassword"	: "1",
-				"url"		: "http://flickrtest1.userland.com/"
-			}
-		]
-	}
-})
- In JavaScript, displaying a list of a user's blogs is then straight forward:
+  {
-function jsonFlickrApi(rsp){
+   "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"
+           }
+          ]
+  }
-	if (rsp.stat != &quot;ok&quot;){
+&lt;/code&gt;
-		// something broke!
+In JavaScript, displaying the logs is then straight forward:
-		return;
-	}
-	for (var i=0; i<rsp.blogs.blog.length; i++){
+<code javascript>;
+  function showLogs(rsp){
-		var blog = rsp.blogs.blog[i];
+    if (rsp.stat != "ok"){
+      // something broke!
+      return;
+    }
-		var div = document.createElement('div');
+    for (var i=0; i<rsp.logs.length; i++){
-		var txt = document.createTextNode(blog.name);
+      var div = document.createElement('div');
+      var txt = document.createTextNode(rsp.logs[i].author);
+      div.appendChild(txt);
+      document.body.appendChild(div);
+    }
+  }
+</code>;
-		div.appendChild(txt);
+===== Failure Responses =====
-		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:
-Failure responses also call the jsonFlickrApi() method, but with a different JSON object. The object is not structured like the REST failure responses - instead it's simplified for JSON. For example:
+<code javascript>
-jsonFlickrApi({
+  {
-	"stat"		: "fail",
+    "stat": "fail",
-	"code"		: "97",
+    "code": "97",
-	"message"	: "Missing signature"
+    "message": "Error message"
-})
+  }
+</code>
- From JavaScript, you can check rsp.stat for failure, and then read the error from rsp.code and rsp.message.
+From JavaScript, you can check rsp.stat for failure, and then read the
+error from rsp.code and rsp.message.
-Callback Function
+===== Callback Function =====
-If you just want the raw JSON, with no function wrapper, add the parameter nojsoncallback with a value of 1 to your request.
+To define your own callback function name, add the parameter **jsoncallback** with your desired name as
+the value.
-To define your own callback function name, add the parameter jsoncallback with your desired name as the value.
+no jsoncallback	-> {"stat":"ok",...}\\
-nojsoncallback=1	-> {...}
+jsoncallback=wooYay -> wooYay({"stat":"ok",...});
-jsoncallback=wooYay	-> wooYay({...});

doc.arkadia.com

User Tools

Site Tools

Differences

Page Tools