English | Site Directory

OpenSocial API Specification (v0.6)

Contents

  1. Overview
  2. Compliance
  3. Background
    1. Key Concepts
      1. People
      2. Relationships
      3. Activities
      4. Persistence
      5. Surfaces
    2. API Patterns
      1. Making requests
      2. Capabilities discovery
      3. Request*
      4. Profile Fields
      5. Sending content to remote servers
    3. Using the API reference
      1. Virtual typing
      2. Parameter Maps

Overview

OpenSocial is a set of APIs for building social applications that run on the web. OpenSocial's goal is to make more apps available to more users, by providing a common API that can be used in many different contexts. Developers can create applications, using standard JavaScript and HTML, that run on social websites that have implemented the OpenSocial APIs. These websites, known as OpenSocial containers, allow developers to access their social information; in return they receive a large suite of applications for their users.

The OpenSocial APIs expose methods for accessing information about people, their friends, and their data, within the context of a container. This means that when running an application on Orkut, you'll be interacting with your Orkut friends, while running the same application on MySpace lets you interact with your MySpace friends. For more information on the types of information exposed by the OpenSocial API, see the Key concepts section.

This document describes the concepts and principles behind the OpenSocial Javascript APIs. It is a complement to the Javascript API Reference, which covers the details of specific methods and parameters. This document does not describe any particular implementation of the API.

Compliance

So what does it mean to be an OpenSocial container? In a practical sense, it means that a site can run any application built on the OpenSocial APIs. This implies a number of things:

  1. The container must implement all methods in the Javascript API Reference.

    Methods may return the error code opensocial.ResponseItem.NOT_IMPLEMENTED for a specific method if the container does not support a specific request. No additional public methods or classes may be put on the opensocial namespace at any level. The required methods and fields are defined in the following JavaScript files:

  2. The container must only use the specified extensibility mechanisms for any container-specific extensions.

    Extra person, activity or other object fields should be defined in an enum under the container's namespace, and the environment should make support for the extended field discoverable. For example, if the field orkut.PersonField.SPECIAL_FIELD is defined as "orkut.specialPersonField", then opensocial.getEnvironment().supportsField("person", "orkut.specialPersonField") and opensocial.getEnvironment().supportsField(opensocial.Environment.ObjectType.PERSON, orkut.PersonField.SPECIAL_FIELD) should both return true.

    Any extra methods may be added to the container's own namespace, and the environment should make support for the method discoverable. That is, opensocial.getEnvironment().hasCapability(functionName) should return true for these additional functions.

    Any extra data request types should be available with a namespaced call like myspace.newFetchAlbumRequest. The gadget would then use batchRequest.add(myspace.newFetchAlbumRequest(...)).

    Any extra objects may be added to the container's own namespace. These objects can be returned from person.getField or other similar requests.

  3. The container must be able to render OpenSocial applications.

    The code of an OpenSocial application is made up of standard HTML and Javascript. Once the code is written, it is then packaged as a "gadget", described using an XML module spec that contains the code and any needed metadata. OpenSocial containers need to be able to render that code into their pages, typically by parsing the gadget spec.

Background

This section is intended to introduce the concepts and principles behind the OpenSocial API, and is for informational purposes only. That is, compliance is determined solely based on the previous section and the detailed API Reference.

Key concepts

Social applications revolve around people and their relationships. OpenSocial provides a standard way for websites to expose their social graph and more. Seeing the activities of other people helps you stay up to date with your friends, and allows everything from resumes to videos to spread virally through the graph. OpenSocial also provides a way for application data to persist on a social networking site, as well as specifying the different ways that an application can be viewed within an OpenSocial container.

People

It's people! Social graphs are made out of people! People are a fundamental part of social networking software and the OpenSocial API. The Person object provides access to a user's information. Part of this information is stored in the user's profile and, depending on the site, can include anything from "favorite TV shows" to "5 things you'll find in my bedroom." The other important user information is the set of connections they have in the social graph and this is covered in the Relationships section.

There are two Person objects that can be requested directly—the VIEWER and the OWNER. To understand the distinction, imagine you're checking out a coworker's profile on Orkut. In this case, you are the VIEWER and your coworker is the OWNER. It's also common to view your own profile, in which case you are both the VIEWER and the OWNER, and some applications may choose to handle this case differently. OpenSocial also provides for the case of anonymous viewing, where the gadget will not be able to access the VIEWER's information.

The API Reference contains more detailed information about the Person class.

A note about user IDs

One of the pieces of data that is always returned with a Person object is the user's ID. The user ID must be alphanumeric (A-Za-z0-9) and must uniquely identify the user in a container. This standardization is intended to allow for prefixing IDs with a domain name and separator to create globally unique IDs (e.g. "orkut.com:34KJDCSKJN2HHF0DW20394"). Note that there will likely be a size limit placed on user IDs to help manage storing IDs in a database.

Relationships

The ability to create relationships is what turns a multi-user application into social software. Being able to share information and interact with friends changes the dynamic of user experience—you're engaging with people, not software.

There are two collections of Person objects that can be requested directly—VIEWER_FRIENDS and OWNER_FRIENDS. In the case where you're checking out a coworker's profile, requesting VIEWER_FRIENDS will return the set of users that are friends with you, while requesting OWNER_FRIENDS will return the set of users that are friends with your coworker. Logically, if you're viewing your own profile, VIEWER_FRIENDS and OWNER_FRIENDS will be the same set of users. Also, if the container support anonymous profile browsing, then the application won't be able to access the set of VIEWER_FRIENDS.

Note that OpenSocial makes no assumptions about the relationship between VIEWER and OWNER. The VIEWER and OWNER could be friends, but if you're looking at a stranger's profile, there's no relationship between you, the VIEWER, and them, the OWNER.

Activities

Since we can't be online all the time, it helps to have a record of what our friends have been up to, so long as your friends want to share that record. Seeing how other people are interacting with a social application also allows you to learn new features and uses of the application, so activity streams are one of the major drivers for organic growth of applications.

OpenSocial exposes activity streams, which are a collection of actions a user has taken in the context of a given container. These activities can include interaction with the container itself, such as updating your profile or installing a new gadget, or interaction with an OpenSocial application, such as sending your friend a virtual gift or setting a new high score in a game.

The API Reference contains more detailed information about the Activity class.

Persistence

Applications can provide a richer user experience if they can save their state between sessions. OpenSocial defines a data store that applications can use to read and write data, which also means some app developers don't have to run their own servers to have powerful apps. There are three possible scopes for this data:

  • Global - This data is shared across all users of an application. This data store is readable, but not writable from the JavaScript API.
    [Editor's Note: Global application data will only be writable via the RESTful data APIs so you can't access information in this scope as of v0.6]
  • User - This data is specific to a particular user. This data store can be read by anyone who can see the gadget, but only the VIEWER's user-scoped data is writable.
  • Instance - This data is specific to each installation of an application (even if a user installs the same gadget twice). This data store can be read by anyone who can see the gadget instance. Like user-scoped data, you can only request to update the VIEWER's instance-scoped data, but this request will only be successful if the OWNER and VIEWER are the same.

For example, consider a daily horoscope application. Every day the global application data could be updated with a horoscope for each of the twelve signs of the Zodiac. Every user that installs the application may be able to configure the color or size of the application, and this information is scoped to the user. Now, maybe you want to install the application twice, once for your horoscope and once for your sweetheart's, because you don't have the same sign. The application could store the sign information in the instance scope, and the two installations on your profile would use different data.

Clearly this free data store could be abused, so containers may implement quotas or rate limits to preserve their disk space. However, OpenSocial does not currently define these policies.

The keys that developers specify to the Persistence API must only contain alphanumeric (A-Za-z0-9) characters, underscore(_), dot(.) or dash(-).

Surfaces

OpenSocial applications may be rendered in different locations of a container, each with different sizes and context. Each of these locations is a surface and the OpenSocial API provides a way for the application to ask what surface it is currently being rendered on, as well as what surfaces the container supports.

Containers can define their own surfaces with different characteristics and abilities. A couple of common surface examples are:

  • Profile - A gadget on the profile is rendered alongside other applications in the user's profile, so it will be smaller and can't support passing URL parameters from the container to the gadget.
  • Canvas - A gadget in canvas mode is rendered by itself, so it will have lots of real estate and URL parameters passed to the container page can be forwarded to the gadget.

API Patterns

This section describes several common patterns in the OpenSocial API. Understanding these concepts should help you wade through the API Reference.

Making Requests

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.DataRequest and add several individual request objects to it. Upon receiving the DataRequest, 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.

Capabilities Discovery

The OpenSocial specification determines the common API that all containers will support, but there are cases where a certain method or a profile field will be offered as an extension in some containers. To help developers write gadgets that can take advantage of these extensions, yet degrade gracefully in their absence, the OpenSocial API includes opensocial.Environment.hasCapability and opensocial.Environment.supportsField methods to query the container at runtime and determine which features are available.

Of course, OpenSocial has compliance rules that must be adhered to by containers wishing to extend the API.

Request*

There are cases where a gadget may wish to perform an action that needs approval by the user or mediation by the container. OpenSocial supports "request" features that allow the container to decide how to handle the interaction with the user. Functions like opensocial.requestCreateActivity, opensocial.requestNavigateTo, and opensocial.requestPermission allow the container to inject its own policy decisions into the gadget execution flow and notify the gadget of the result. Under this specification, it is equally valid for a container to defer to the user, always approve, always deny, or use any other method to determine responses to request calls. Additionally, this allows the container to enforce UI flows in a safe and integrated way.

Profile fields

User profiles are different from container to container. On consumer-oriented containers, applications may be interested in a user's idea of a perfect first date, but this may not be appropriate for business-oriented containers. This is why OpenSocial allows containers to extend Person objects with arbitrary fields - to match the feel and uses of each container site. Profile fields are therefore obtained through Person.getField calls rather than having hardcoded getters and setters for each property. See the Compliance and Capabilities discovery sections for more information about how containers can add additional data to the API, and how applications can determine which fields are available for use.

Fetching content from remote servers

OpenSocial applications use the opensocial.makeRequest mechanism to pass data from gadgets back to application servers in a way that cannot be spoofed. The container is expected to mediate communications from the gadget to the application server (e.g. ilike.com). Therefore trusted content fetching has two main steps: [1] the gadget contacts the container, and [2] the container contacts the application server.

For step 1 (gadget to container), the container needs to be able to validate any parameters it knows about: the viewer id, the owner id (if known), and the application id. Validating these parameters is an implementation detail that may vary between containers. For example, Orkut uses an encrypted token passed in the document fragment of the gadget URL.

For step 2 (container to application server), the app server needs to be able to validate that the parameters really came from the container (and were not forged by some other entity). OpenSocial uses OAuth's parameter signing algorithm. Note that most of the OAuth standard, including token exchange, is not required; OpenSocial only plans to use the parameter signing piece of the standard (including timestamp and nonce). OpenSocial permits the HMAC-SHA1 method (except that the key is a shared secret between container and app, not a concatenation of tokens as specified in section 9.2 of the OAuth spec) and the RSA-SHA1 method. HMAC-SHA1 is faster and easier to implement, but it requires more coordination than RSA-SHA1.

Using the API reference

The JavaScript API reference is a complete listing of the methods and fields that OpenSocial requires, but some conventions are not immediately understandable. This section will explain some of the assumptions used in generating the API reference.

Virtual typing

JavaScript is not strongly typed, but in order to make the developer experience consistent, the APIs are defined as if JavaScript supported strongly typed data. Cases where a parameter or return value are defined as a certain type in the documentation indicate that this is the only type that can be provided or accepted for OpenSocial compatibility. Any exceptions to this rule will be directly documented in the reference.

As an example, the getErrorCode method is defined in the JavaScript API reference as returning a value of the type opensocial.ResponseItem.Error, although in practice this value will be a normal JavaScript string. However, developers can be assured that in a compliant container, the string returned is one of the opensocial.ResponseItem.Error fields.

Enumerations figure heavily into the OpenSocial API. Developers are permitted to reference an enum or use the enum's value directly. To avoid collisions related to extensibility, containers must ensure that the names and values for an enum match the ones defined in the spec and that custom values are namespaced appropriately. For example, an Orkut custom field named MY_PERSON_FIELD could have a name of Orkut.PersonField.MY_PERSON_FIELD and a value of "Orkut.myPersonField". See the Compliance and Capabilities discovery sections for more information.

Parameter maps

Many of the OpenSocial methods have a large number of optional parameters. JavaScript's lack of strong typing makes overloading difficult at best, and having functions with a large amount of parameters can be difficult to manage (especially for developers not using a nice IDE). OpenSocial uses the "object bag" approach to optional parameters - many methods take an additional opt_params parameter that takes the form of a map of parameter names to their corresponding values.

For each method which uses an opt_params map the spec defines all of the valid fields that will be read out of the map by the container. These fields have defined types as discussed in the Virtual typing. If a developer adds an invalid value for a field in the map the container should return the BAD_REQUEST error code.