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:34] admin |
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]]. | about JSON, visit [[http://www.json.org]]. | ||
- | To return an API response in JSON format, send a parameter "output_format" in the | + | To return an API response in JSON format, send a parameter "**output_format**" in the |
request with a value of "json". | request with a value of "json". | ||
- | === Object Representation === | + | ===== Object Representation ===== |
Some simple rules are used when converting REST XML into JSON objects. | Some simple rules are used when converting REST XML into JSON objects. | ||
Line 15: | Line 15: | ||
<code xml> | <code xml> | ||
- | <foo bar="baz" /> | + | <foo bar="baz" /> |
</code> | </code> | ||
- | <code json> | + | <code javascript> |
- | { | + | { |
- | "foo": { | + | "foo": {"bar": "baz"} |
- | "bar": "baz" | + | } |
- | } | + | |
- | } | + | |
</code> | </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: | + | Each element is represented by a JSON object. Element attributes are represented by an object member |
- | <foo bar="baz"> | + | with a string value. Child elements are represented by an object member with an object value: |
- | <woo yay="hoopla" /> | + | |
- | </foo>{ | + | |
- | "foo": { | + | |
- | "bar": "baz", | + | |
- | "woo": { | + | |
- | "yay": "hoopla" | + | |
- | } | + | |
- | } | + | |
- | } | + | |
- | Element text nodes are represented as if they were an attribute, using the special name "_content": | + | <code xml> |
- | <foo>text here!</foo>{ | + | <foo bar="baz"> |
- | "foo": { | + | <woo> |
- | "_content": "text here!" | + | <yay>hoopla</yay> |
- | } | + | </woo> |
- | } | + | </foo> |
+ | </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 javascript> |
- | <outer> | + | { |
- | <photo id="1" /> | + | "foo": { |
- | <photo id="2" /> | + | "bar": "baz", |
- | </outer>{ | + | "woo": {"yay": "hoopla"} |
- | "outer": { | + | } |
- | "photo": [ | + | } |
- | { | + | </code> |
- | "id": "1" | + | |
- | }, | + | |
- | { | + | |
- | "id": "2" | + | |
- | } | + | |
- | ] | + | |
- | } | + | |
- | } | + | |
- | Successful Responses | + | |
+ | 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: | 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, flickr.blogs.getList has a documented response as follows: | + | The single object passed in the function call represents the REST outer <rsp> element. |
- | <blogs> | + | The root element of the REST response is then a member of this object (the stat param also is - |
- | <blog id="73" name="Bloxus test" needspassword="0" | + | check this to see if the call was successful). For instance, get_wwwfile_logs has a |
- | url="http://remote.bloxus.com/" /> | + | documented response as follows: |
- | <blog id="74" name="Manila Test" needspassword="1" | + | |
- | url="http://flickrtest1.userland.com/" /> | + | |
- | </blogs> | + | |
- | And the Flickr JSON equivilent would be: | + | <code xml> |
- | jsonFlickrApi({ | + | |
- | "stat": "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: | + | <rsp stat="ok"> |
- | function jsonFlickrApi(rsp){ | + | <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> | ||
- | if (rsp.stat != "ok"){ | + | </code> |
- | // something broke! | + | And the JSON equivilent would be: |
- | return; | + | |
- | } | + | |
- | for (var i=0; i<rsp.blogs.blog.length; i++){ | + | <code javascript> |
- | var blog = rsp.blogs.blog[i]; | + | { |
+ | "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" | ||
+ | } | ||
+ | ] | ||
+ | } | ||
- | var div = document.createElement('div'); | + | </code> |
- | var txt = document.createTextNode(blog.name); | + | |
- | div.appendChild(txt); | + | In JavaScript, displaying the logs is then straight forward: |
- | document.body.appendChild(div); | + | |
- | } | + | |
- | } | + | |
- | Failure Responses | + | <code javascript> |
+ | |||
+ | function showLogs(rsp){ | ||
- | 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: | + | if (rsp.stat != "ok"){ |
- | jsonFlickrApi({ | + | // something broke! |
- | "stat" : "fail", | + | return; |
- | "code" : "97", | + | } |
- | "message" : "Missing signature" | + | |
- | }) | + | 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. | + | 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({...}); | + | |