Next Steps for OpenSocial v0.8 and draft release notes

[Dan Peterson]

Hi everyone,

As Cassie noted, we've reached consensus and closure on the items wrapped into the next version 0.8 OpenSocial spec! This is a great milestone, and something we should all be proud of accomplishing together. To find the detailed list of additions, please look at the "approved changes" tab in http://spreadsheets.google.com/pub?key=pigtmOB55Aw_YJHz040u0Kg&gid=0

In my view, the next step to making OpenSocial v0.8 "real" is to get the full spec and JS files ready so we can look at a complete draft. There are some folks working on doing just that, and we're planning to have a draft to share in the latter half of this week. With that full draft, it seems reasonable to let it bake for a bit more than a week, so we can hammer out any nits before making it "golden."

For now, I'd love input on the below (first iteration of the) release notes.

What important things are missing? How can the wording be improved for clarity?

For reference, past release notes (for 0.6 and 0.7) are captured at: http://code.google.com/apis/opensocial/docs/releasenotes.html


OpenSocial v0.8

• A specification for a RESTful API was adopted to allow non-JavaScript data access (e.g. for mobile applications, server sync, etc)
  

opensocial.* JavaScript changes

• Developers now have more control over the auto escaping of data. First of all, all data in the datastore is no longer treated as a String, but as JSON. This will allow containers to do more intelligent auto escaping. And second, now both the fetch data method and all of the getField methods take in an escapeType flag which allows developers to turn off escaping altogether. Certainly, to ensure app security, developers need to be cautious about using unescaped data.
  

• A new function, newRemovePersonAppDataRequest(), was introduced that developers can use to remove data from the datastore (e.g. to free up quota).

• The person object has added additional fields and filters: a more structured lookingFor field, a new hasApp field, and a new networkPresence field. An ability to filter people by the new top friends filter or the isFriendsWithFilter was introduced. Developers can use the latter to query for all people who are friends of the owner and viewer.
  

• The message object now has titleId and bodyId fields so that messages can use templates just like activities.

• A new limitExceeded error code was added to the response items to indicate when some quota has been exceeded.

• Constructing navigation URLs no longer requires synchronous JavaScript calls. A container is now able to specify a template for an app's URL, so a developer is able to construct URLs ahead of time using opensocial.getContainerUrlTemplate (e.g. a URL might have the form http://apps.container.com/${name}#${path}?${params}).
  

• The requestShareApp method now lets the developer set some navigation context that the user will see when they accept an invite as well as set what the user will see after sharing the app.

gadgets.* JavaScript changes

• The specification for gadgets.io.makeRequest has been further clarified in numerous ways: the OAuth authorization type has been explained, and a common set of signed request parameters has been adopted.

• Developers have greater control over their app's user experience: added the ability to specify the refresh interval on gadgets.io.getProxyUrl, and an optional owner id has been added to gadgets.views.requestNavigateTo.

• A new function, gadgets.util.sanitizeHtml(), was added to allow developers to get HTML in a presentation-ready format.

• The view types have been modified to reflect the most well-known set of views (e.g. home, profile, canvas, preview)

• A new feature, pubsub, was introduced to allow developers to send strings between multiple gadgets.

gadgets XML changes

• Message bundles can now be inlined into the gadget xml, and no longer have to be in a separate file.

• The Preload element now accepts an authz param to specify that preloaded data should be fetched with signed requests.

• There is a new Link tag that can be used within the ModulePrefs section to will allow containers to use new links types like gadgetsHelp and gadgetsSupport.

• To improve localization support, substitutions are now supported for all hangman variables that get displayed to users (e.g. all Module.ModulePrefs attributes, UserPref@display_name).

• The ModulePrefs section can now be used to specify URLs for usage of OAuth.
  

• Gadgets now support lifecycles events. A developer can place link tags in their gadget xml which specify URLs the container should hit when a type of event occurs. This way a gadget can be notified of all app installs or uninstalls.

• Each Content section can now be specified with a preferredHeight or preferredWidth tag. This means that gadgets with multiple views can have different default heights.