15. Porting Your App to OpenSocial 0.9

We have some good news and some bad news. Let’s go with the bad news first. The bad news is that the OpenSocial spec is currently in constant flux while the spec group seeks the Holy Grail of version 1.0. You may think that this isn’t so bad. After all, you logically go from version 0.8 to 0.9, then finally 1.0, right? Well, there is currently some talk of going from 0.8 to 0.9 to 0.10. That’s right: zero dot eight, zero dot nine, zero dot ten.

We hope that won’t be the case and that the 0.9 spec will be stable enough that it can be called version 1.0 without too many changes. If that’s what happens, the spec should stop churning for a while, excluding a few bug fixes here and there.

The other piece of bad news is that MySpace will probably continue to support the latest and greatest versions of the OpenSocial spec as they are released. That means version 0.9 will have the full support of MySpace. Sounds great, right?

Well, if your app is currently written in version 0.7, that means you’ll now be two spec versions behind. The more versions that are released and supported by MySpace, the more likely it is that the older versions will receive less and less support. We’re already seeing this phenomenon to some extent. Bug fixes and feature releases for 0.7 are fewer and farther between compared to those for 0.8.

Fortunately, the good news more than makes up for the bad. For the foreseeable future, MySpace will continue to support older versions of the OpenSocial spec. It’s a lot of effort to deprecate older versions of the spec, and too many apps are running on old versions. It will happen eventually, but it will probably be a long and drawn-out process. A little-known fact is that the 0.7 container actually also supports OpenSocial 0.6, an early and buggy release of the spec. By the time you read this page, dear readers, version 0.6 will be about two years old (or more)—an eternity in Internet time. If version 0.6 can last that long, and probably longer, then version 0.8 will be around for a long time as well.

Even better news is the fact that when it comes down to it, not a whole lot is changing from version 0.8 to version 0.9. The biggest change will be the inclusion of OSML to the spec. Since we covered OSML extensively in Chapters 10 and 11, we won’t rehash that topic here. The other big change is what is called “OS Lite,” or the “Lightweight JS APIs.” OS Lite is, for the most part, a rewrite of the OpenSocial JavaScript APIs and has two main goals: to unify the JavaScript and REST APIs, and to use JSON for both inputs and outputs. These are both worthy goals, but the truth of the matter is that the original APIs will work just fine in version 0.9. Moving forward, OS Lite will probably become the standard, but it’s probably best to wait for version 1.0, when it becomes a bit more baked-in.

Other than that, there are a few bug fixes, a feature or two, and a bit of a cleanup. Now, let’s take a look at the big changes.

Media Item Support

A slew of functions to support media items were added in 0.9; this includes fetches, updates, deletes, and (finally!) uploads. However, some of this functionality already existed on the MySpace platform as MySpace-specific extensions in 0.8.

In the sections that follow, we’ll take a look at the new APIs and, if applicable, contrast them with the 0.8 APIs. Then we’ll show some sample code so you can see how to use the new features.

opensocial.Album

The first thing we’ll look at is the new opensocial.Album object. The album object behaves exactly like the other OpenSocial objects, such as opensocial.Person; it has fields, and those fields are fetched with getField. Let’s take a look at the available fields that albums provide.

OpenSocial 0.9^*

^*Code courtesy of OpenSocial.org: http://sites.google.com/site/opensocialdraft/Home/opensocial-javascript-api-reference/albums-js.

OpenSocial 0.8 on MySpace

The entities are basically the same—all the important stuff is there in both cases, such as IDs, album cover URL, and the number of media items in the album.

Fetching Albums

Here’s the functionality for fetching an album. First, let’s look at OpenSocial 0.9.

OpenSocial 0.9^†

^†Code courtesy of OpenSocial.org: http://sites.google.com/site/opensocialdraft/Home/opensocial-javascript-api-reference/datarequest.

And now, the MySpace 0.8 extension.

OpenSocial 0.8 on MySpace

There are no real functional differences between versions. The new version uses an IdSpec object instead of a plain old string ID. It can specify a particular album, whereas 0.8 had a separate endpoint for that, and the paging parameters are in a different namespace.

Here’s an example function that takes in optional paging parameters, album ID, and callback function and makes a request for the Viewer’s photo albums:

In the function we specified opensocial.MediaItem.Type.IMAGE. The other possibility is opensocial.MediaItem.Type.VIDEO.

Fetching Media Items

Let’s look at the OpenSocial 0.9 method for fetching media items.

OpenSocial 0.9^‡

^‡Code courtesy of OpenSocial.org: http://sites.google.com/site/opensocialdraft/Home/opensocial-javascript-api-reference/datarequest.

And now for version 0.8.

OpenSocial 0.8 on MySpace

The big difference here is that the 0.9 API combines two MySpace 0.8 APIs into one, and it again uses an IdSpec object and modifies the paging parameter namespaces.

In our Tic-Tac-Toe app, we had a function that fetched the Viewer’s photos; we’ll reproduce it here so that you can see the differences between versions.

Version 0.8 Function for Fetching Viewer’s Photos

Let’s now convert that code into 0.9.

Version 0.9 Function for Fetching Viewer’s Photos

Again we specified opensocial.MediaItem.Type.IMAGE, but opensocial.MediaItem.Type.VIDEO is supported as well.

Updating Albums and Media Items

These are APIs that allow you to update the metadata of albums and media items, not actually upload new ones. There are no 0.8 substitutes for these endpoints:^§

^§Code courtesy of OpenSocial.org: http://sites.google.com/site/opensocialdraft/Home/opensocial-javascript-api-reference/datarequest.

Let’s take a look at a quick example. The following function can be used to update the title, thumbnail URL, and description of a particular media item in a particular album. Since the functionality to update an album is very similar, we’ll leave it as an exercise for the reader to create a function to do so.

Uploading Media Items

One of the big new features added to the spec is the ability to upload media. Sending the actual contents of an image isn’t very easy in JavaScript, so because of this the upload functionality works similarly to opensocial.requestSendMessage and opensocial.requestShareApp. You invoke opensocial.requestUploadMediaItem and a pop-up modal appears. The pop-up itself takes care of the actual uploading process. On MySpace either a Flash or a Java-based widget is used, depending on the end user’s system. Initially, only images are available for upload.

Once an image has been uploaded and the user closes the pop-up window, a callback function is executed. The one parameter passed to this callback is an opensocial.ResponseItem object. This object contains information on any error that may have occurred, or an array of opensocial.MediaItem objects if there were any successful uploads.

An example is in order:

There are a couple of functions in the code. The first just wraps opensocial.requestUploadMediaItem. The second is specified as the callback function and handles the result of the attempted image upload. The response is checked for an error, and if one is found, we parse the error field for data. The error code is set as normal and should give you a good idea of what went wrong. The error message is a comma-delimited list of the files that had an error. If there was no error, either the user canceled the pop-up window or some files were uploaded.

If the upload was successful, the data portion of the response contains an array of opensocial.MediaItem objects, one for each successfully uploaded image. If the array has a length of zero, you can assume the user canceled the action; otherwise you’re free to parse the array as you see fit. In our case, we simply iterate through the list of images and output them to the UI.

Simplification of App Data

The functionality of app data has remained constant between versions, but the APIs used to interact with it have been significantly simplified. The original API was deemed to be too complex for what was actually allowed. For example, it was possible to update the app data only for the Viewer, yet the function accepted an ID as a parameter even though its only valid value was VIEWER.

To that end, the signatures for updating and deleting app data were modified. The following is what they used to look like.

Version 0.8 (Updating and Deleting App Data)

They have now been changed for 0.9.

Version 0.9 (Updating and Deleting App Data)

It’s a very simple change; you’ll literally just have to go through and remove the ID you were passing in.

Updating and deleting app data weren’t the only APIs to be simplified; fetching app data also got a once-over. The entire opensocial.DataRequest.newFetchPersonAppDataRequest function was deprecated. Instead, app data was attached to the opensocial.Person object. Let’s take a look at an example:

This function fetches the app data for either the Viewer or the Owner. First an array of strings is created with all the app data keys we’d like to fetch—in this case we’d like to fetch three keys. Those keys are added to the parameter object via the opensocial.DataRequest.PeopleRequestFields.APP_DATA enum. The id variable can be either opensocial.IdSpec.PersonId.OWNER or opensocial.IdSpec.PersonId.VIEWER. The request is then sent as normal.

Some small modifications are required to fetch the app data for the Owner’s or Viewer’s friends. The basic idea is to do everything as we did in the previous code sample but use opensocial.DataRequest.newFetchPeopleRequest instead. Note that when fetching friends, you need to provide an opensocial.IdSpec object instead of a string ID; see Chapter 3, Getting Additional MySpace Data, for details on that.

To retrieve the app data in the callback, you must use a function that has been added to the opensocial.Person object:^**

^**Code courtesy of OpenSocial.org: http://sites.google.com/site/opensocialdraft/Home/opensocial-javascript-api-reference/person.

You simply pass in the key of the app data you’re looking for, and the value is returned. Let’s look at an example:

The values of val1, val2, and val3 are the JSON objects that were stored in app data for key1, key2, and key3 respectively or undefined if nothing was found for that key.

REST APIs

For those of you using iframe apps and the REST APIs, there’s not too much change for you either. The SDKs will be updated to point to the new APIs, so the change should be invisible to you. Simply get the updated SDKs from the usual place: http://code.google.com/p/myspaceid-sdk/.

Replace your existing source files with the new ones. If any of this sounds mysterious to you, check out Chapters 8 and 9 (where we cover OAuth and external iframe apps) for details. That should set you up with hitting the updated APIs. Unfortunately, it’s not quite that easy, since the responses of some of the APIs have been slightly modified. This difference in the response between versions exists because the MySpace 0.8 APIs weren’t quite to spec, but now in 0.9 they are. So it’s not that the spec changed; it’s just that MySpace is now compliant. Let’s take a look at the two most important APIs, person and friends, and take a look at how they’ve changed.

This is a sample response from the 0.9 REST API for a friend list:

Meanwhile, a sample response from the 0.8 REST API looks like this:

So, there are some small differences there; you’ll have to make some modifications to your mapping code to compensate. For example, in Chapter 9 we pushed the results of the friend list call down onto the client in a JavaScript object called friends. We then used friends like this:

TTT.Lists.getCurrentList().list = friends.Friends;
TTT.Lists.getCurrentList().total = friends.count;

In 0.9 that code would become

TTT.Lists.getCurrentList().list = friends.entry;
TTT.Lists.getCurrentList().total = friends.totalResults;

Essentially Friends becomes entry and count becomes totalResults. You can see this difference in the two sample responses shown earlier.

Also, some other code accessed the individual fields for each friend:

That code would need to be converted to the following for 0.9:

Notice that a user’s ID changed from just an integer, like 6221, to something a little more complex; it now looks like myspace.com.person.6221.

As for the person endpoint, let’s take a look at a sample response from the 0.9 REST API when all the person fields are requested:

And let’s compare that to the sample response generated by the older API in Chapter 9, External Iframe Apps:

Again, there are quite a few differences. Fortunately most of the same data is present in 0.9, so it’s basically the same data presented in a different way. For the friends endpoint earlier, we showed the client-side code modifications necessary to make use of the new JSON object that will be generated. Here we’ll leave it as an exercise for the reader. Well, okay ... one example. In Chapter 9 we requested the Viewer’s data and output all the fields to the UI. To parse the Viewer’s display name from the response from the REST API, we did this:

sb.append(viewer.fullprofile.basicprofile.name + "<br>");

In the updated 0.9 response, the display name would be accessed like so:

sb.append(viewer.person.displayName + "<br>");

Summary

There are a few more small tweaks between OpenSocial versions 0.8 and 0.9 coming down the OpenSocial pipeline, but the bulk of the changes that will directly affect porting your apps can be found in this chapter. However, this chapter has a couple of “sister” chapters that deal with the biggest change in 0.9: OSML. To learn more about OSML, see Chapter 10, OSML, Gadgets, and the Data Pipeline, and Chapter 11, Advanced OSML.

Overall, we think you’ll find that MySpace’s implementation of version 0.9 is cleaner and more spec-compliant; after all, it’s the third iteration, and we all (we hope) learn from our mistakes, even MySpace developers.

Deciding when and why to port your app is a question you’ll have to answer for yourself. You’ll have to weigh the benefits and the costs since porting your apps isn’t free. There will be extra development and testing time, not to mention the research time that came from reading this chapter. One of the ways MySpace tries to get app developers to upgrade their apps is to release new features only on the latest and greatest version. So you may want to wait until some killer new feature is released before you port your app. Or you may just want to play around with the newest version of the spec. The choice is yours.