Updating your apps to use the IdSpec object in OpenSocial 0.8

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.