August 2008 Archives

Lately I've been updating some documentation to use version of 0.8 of the OpenSocial specification.  If you've developed on the 0.7 version of the API, you'll probably be happy to see that not a lot of breaking changes have been introduced in the new version, with one major exception: the IdSpec object.

In the past, when you wanted to specify a single person or a group of people, you would use one of the following:

Single person specifiers (OpenSocial 0.7):

• opensocial.DataRequest.Person.OWNER
• opensocial.DataRequest.Person.VIEWER
• A string representing the OpenSocial ID of a person.

Multiple person specifiers (OpenSocial 0.7):

• opensocial.DataRequest.Group.OWNER_FRIENDS
• opensocial.DataRequest.Group.VIEWER_FRIENDS
• An array of strings, each representing the OpenSocial ID of a person.

In 0.8, the idea of an IdSpec object was introduced.  IdSpec allows you to be much more expressive when specifying groups of people (including friends-of-friends, covered later) but introduces some additional complexity.  Single person specifiers still use the OWNER and VIEWER objects, but these have been moved to the opensocial.IdSpec.PersonId namespace.

To convert your app, update all functions that take a single person identifier to one of the following:

• opensocial.IdSpec.PersonId.OWNER
• opensocial.IdSpec.PersonId.VIEWER
• A string representing the OpenSocial ID of a person.

Note that only the following take a single person modifier:

• opensocial.DataRequest.newFetchPersonRequest
• opensocial.DataRequest.newUpdatePersonAppDataRequest
• opensocial.DataRequest.newRemovePersonAppDataRequest 
  

The last two only accept the value of opensocial.IdSpec.PersonId.VIEWER, so this is a pretty straightforward change.

Seleting a group of people requires a bit more of a code change, though.  Where you might write something like this in OpenSocial 0.7:

var params = {};
var req = opensocial.newDataRequest();
...
req.add(req.newFetchPeopleRequest(
    opensocial.DataRequest.Group.OWNER_FRIENDS, params);
req.send();

Now you need to create an IdSpec instead:

var params = {};
var idspec = opensocial.newIdSpec({ 
    "userId" : "OWNER", 
    "groupId" : "FRIENDS" 
});
...
req.add(req.newFetchPeopleRequest(
    idspec, params);
req.send();

You can actually create IdSpec equivalents to all of the old person/people identifiers:

Identifier	IdSpec code
OWNER	var idspec = opensocial.newIdSpec({ "userId" : "OWNER", "groupId" : "SELF" });
VIEWER	var idspec = opensocial.newIdSpec({ "userId" : "VIEWER", "groupId" : "SELF" });
OWNER_FRIENDS	var idspec = opensocial.newIdSpec({ "userId" : "OWNER", "groupId" : "FRIENDS" });
VIEWER_FRIENDS	var idspec = opensocial.newIdSpec({ "userId" : "VIEWER", "groupId" : "FRIENDS" });

You can use these for the following functions:

• opensocial.DataRequest.newFetchActivitiesRequest
• opensocial.DataRequest.newFetchPeopleRequest
• opensocial.DataRequest.newFetchPersonAppDataRequest

The IdSpec object exposes some additional functionality like NETWORK_DISTANCE that I'll cover later, but for the time being, this should be enough information to get you to start porting your existing code to 0.8.

When teaching myself the OpenSocial API, I found the standard "edit XML file" -> "upload to server" -> "reload gadget" process to be too slow for my liking, especially when working with code that was almost completely client-side JavaScript. 

A strength (or weakness, depending on who you ask) of JavaScript is that you can compile and execute JavaScript source code at runtime using the eval function.  It made sense to create a simple gadget to help developers prototype simple OpenSocial calls, so I released CodeRunner, an OpenSocial application that let developers execute JavaScript snippets inside of a live OpenSocial container.  These snippets could also be saved to AppData, which was convenient as long as you didn't run out of quota space (currently 10k on orkut and 1k on MySpace).

CodeRunner wound up working quite well, but I wanted more space for storage, and I wanted to offer some capabilities that only a server-side solution would be able to satisfy.  Because Google released their App Engine product around this time, I decided to turn CodeRunner into an App Engine application, called the Developer Application for OpenSocial, or DAfOS for short.

You can get links to use DAfOS on different containers by visiting dafos.appspot.com.  Eventually that site will be filled out with more documentation. 
 
Here's a shot of DAfOS in action (it looks a lot like CodeRunner at the moment):