OpenSocial JSON data
The previous post about OpenSocial Owner and Viewer data is related to Persistence API . If you use data in your OpenSocial applications, you will be making request to the application container to retrieve or update the data.
OpenSocial Data
OpenSocial specification dictates that the container must support the RESTful Protocol Specification. The container must provide JSON, XML, and AtomPub representations of data.
The OpenSocial API queries the container asynchronously for most of its calls, which is why most OpenSocial methods don’t directly return data, but rather allow you to specify a callback that will be executed when the server’s response is ready. Of course, making lots of asynchronous requests isn’t always ideal, so the API allows for batch requests to allow developers to ask for many pieces of information at once. A developer can create an
opensocial.DataRequestand add several individual request objects to it. Upon receiving theDataRequest, the container can process each request optimally and return the results of each operation as a batched result object. Containers must preserve the semantics of executing requests in serial order, though. A request that contains a write and then a read must return the newly written data, while a request that contains a read and then a write must return the data that was present before the write took place.
What can be understood from the above is; in order to reduce expensive calls to the container, application can make batch request to containers in a single call. The order of the calls for write and read however, should be sequential.
This is one of the features from OpenSocial platform which I think is a good design pattern worth highlighting.
OpenSocial DataRequest
So how do we make data request?
Refer to the OpenSocial API Reference for the DataRequest method summary:
add(request, opt_key)- Adds an item to fetch (get) or update (set) data from the server.
Object newFetchActivitiesRequest(idSpec, opt_params)- Creates an item to request an activity stream from the server.
Object newFetchPeopleRequest(idSpec, opt_params)- Creates an item to request friends from the server.
Object newFetchPersonAppDataRequest(idSpec, keys, opt_params)- Creates an item to request app data for the given people.
Object newFetchPersonRequest(id, opt_params)- Creates an item to request a profile for the specified person ID.
Object newRemovePersonAppDataRequest(id, keys)- Deletes the given keys from the datastore for the given person.
Object newUpdatePersonAppDataRequest(id, key, value)- Creates an item to request an update of an app field for the given person.
send(opt_callback)- Sends a data request to the server in order to get a data response.
The methods are simple, and the sample of calling was previously shown.
What is the format of data returned? How do we use or process it?
JSON
JSON is short for JavaScript Object Notation and is a light-weight computer data interchange format.
If you could understand the images from json.org, I’d say you’re really something.
If not, wikipedia provides a simple human readable explanation.
In a simple manner, I would say JSON is useful in OpenSocial platform as it facilitates in switching format between data in text and to object.
There is this method you will always use for data exchange:
The gadgets.json class is a great tool to switch the JSON string text to a JavaScript value object for usage in application code, and then converts it back to a JSON string for persistence.
It’s really easy.
This example creates a JavaScript array, encodes it as a JSON string, and then converts the JSON string back into an Array object:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="JSON Example">
<Require feature="opensocial-0.7"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<div id="content_div"></div>
<script type="text/javascript">
var html = "";
// Create Array object
var myfriends = new Array();
myfriends[0] = "Touki";
myfriends[1] = "Rowan";
myfriends[2] = "Trevor";
// Encode array as JSON string
var jsonString = toJSON(myfriends);
html += "The JSON string is " + jsonString + "<br />";
html += "The type of jsonString is " + typeof(jsonString) + "<br />";
// Convert JSON string back to an object
var arr_obj = toObject(jsonString);
html += "The type of arr_obj is " + typeof(arr_obj);
document.getElementById('content_div').innerHTML = html;
// Encode object as JSON string
function toJSON(obj) {
return gadgets.json.stringify(obj);
}
// Convert JSON string into an object
function toObject(str) {
return gadgets.json.parse(str);
}
</script>
]]>
</Content>
</Module>
The output from this gadget is as follows:
The JSON string is ["Touki","Rowan","Trevor"] The type of jsonString is string The type of arr_obj is object
For better understanding of this method, I would definitely recommend trying the piece of sample code yourself and then tweaking it or modifying the structure of myfriends.
A point to note though, you should always use the gadgets.util.escapeString to escape the input JSON string so that to avoid having XSS (Cross Site Scripting) exploits to your application. 😉
Follow me on twitter.
Google, OpenSocial, Software