OpenSocial defines a common API for social applications across multiple websites. Built from standard JavaScript and HTML, developers can create applications with OpenSocial that access a social network's friends and update feeds. By using a common API, developers can extend the reach of their applications more quickly, yielding more functionality for users. [1]

This article will be covering all the aspects around the OpenSocial Practice - from the basics of developing an application inside the Social Network (Gadget Container) using the JavaScript API, passing over the use of the RESTful API to code desktop or mobile applications or server-to-server communication, to the implementation of Shindig in a social network so it can be an OpenSocial Container that accepts these applications.

OpenSocial for Application Developers
JavaScript API Overview [2]
This API consists of a set of tools that will allow any application to fully access the social network services. It's intended to be used inside a gadget that renders inside the social network site. Since it's mainly Java-Script, the API is language-agnostic. Developers only need to know HTML + JavaScript to start developing OpenSocial applications.

The four big services that can be accessed from this API are People, Data, Activity Stream, and Messaging.

1.  People Service
This service will provide all the needed information to get the profile of a person, and it will also give you access to the friends of the user (or friends of friends if the container offers that optional service). Note that the user has two different roles. You have the Owner user, the one that owns the application or the profile, and you have the Viewer, the other person who is looking at that application or profile. There is one special case when the Owner and Viewer are the same user, which is when you're visiting your own profile.

// Example code to retieve the viewers profile data
function requestMe() {
var req = opensocial.newDataRequest();
req.add(req.newFetchPersonRequest(
opensocial.IdSpec.PersonId.VIEWER),
"viewer");
req.send(handleRequestMe);
};

function handleRequestMe(data) {
var viewer = data.get("viewer");
// Do something with viewer.getData()...
}

2.  Activity Stream Service
Here are defined all the methods for communicating how the user (the viewer) is interacting with the application. Each activity doesn't have any particular addressee, and each container will handle how to display it in a particular way. This service also allows you to retrieve your friends' activities so you can know what your friends are doing.

3.  Data Service
The data service gives developers a simple space to store the state of the application for each user. You are allowed to store and, obviously, retrieve name/value pairs for each user. You can also get these data from the owner and viewer friends.

4.  Messaging Service
There are four different types of messages: Application Notifications, E-Mails, Private and Public Messages. The containers can implement any or all of these messages that consist in the Title and the Body. Each container can handle the mapping or destination of each message differently.

RESTful API Overview [3]
The RESTful API serves as a common protocol understood by all OpenSocial v0.8.1-compliant clients and servers. This will replace the JSON wired APIs that were used until v 0.7. Having a RESTful API offers a lot of new possibilities such as being usable across a new span of clients such as mobile or desktop applications or server-to-server communications, besides the gadgets running in websites.

The protocol is defined on top of the HTTP protocol and uses the standard HTTP verbs (GET, POST, PUT, DELETE, etc.) to retrieve and update the server data.

This API offers the same four services as the JavaScript API but it uses AtomPub and JSON dual representation for each resource.

For example, to get the Profile record for user {guid} you'll consume this service:

/people/{guid}/@self

The response in AtomPub [4] will be

<entry xmlns="http://www.w3.org/2005/Atom">
<content type="application/xml">
<person xmlns="http://ns.opensocial.org/2008/opensocial">
<name>
<unstructured>Jane Doe</unstructured>
</name>
<gender key=»FEMALE»>female</gender>
</person>
</content>
<title/>
<updated>2003-12-13T18:30:02Z</updated>
<author/>
<id>urn:guid:example.org:34KJDROPUN2HHF0DW20394</id>
</entry>

And in JSON

{
"id" : "example.org:34KJDROPUN2HHF0DW20394",
"name" : {"unstructured" : "Jane Doe"},
"gender" : {"displayvalue" : "female", "key" : "FEMALE"}
}

Security Model
The Security Model is based on the OAuth Standard and you have three different types of implementations. The first one is just sending not signed requests. Obviously this is not recommended but can be useful to avoid the overhead of security while consuming public resources such as an open RSS feed.

var params = {};
var url = ‘http://example.com/webService';
params[gadgets.io.RequestParameters.CONTENT_TYPE] =
gadgets.io.ContentType.TEXT;
// NOT Secure requests
gadgets.io.makeRequest(url, callback, params);

You are left with other two secure options: the Signed and the OAuth requests.

For the Signed Request, the container needs to vouch for the user's identity to the destination server. The container does this by removing some specific request parameters and adding, among others, opensocial_owner_id and opensocial_app_url, and then signing the resulting request according to the OAuth specification. This way in each request the destination server will have all the information needed about the app and the active users, and it can, at the same moment, verify it via a public/private key for the data integrity.

// For SIGNED Type Requests add this param
params[gadgets.io.RequestParameters.AUTHORIZATION] =
gadgets.io.AuthorizationType.SIGNED;

gadgets.io.makeRequest(url, callback, params);

For the OAuth request the procedure consists of several steps in which authentication tokens are exchanged between the application (Consumer) and the server requested (Service Provider).

The OAuth protocol enables websites or applications (Consumers) to access Protected Resources from a web service (Service Provider) via an API, without requiring Users to disclose their Service Provider credentials to the Consumers. More generally, OAuth creates a freely implementable and generic methodology for API authentication.

An example use case is allowing printing service printer.example.com (the Consumer), to access private photos stored on photos.example.net (the Service Provider) without requiring Users to provide their photos.example.net credentials to printer.example.com. [5]

// For OAUTH Type Requests add this param
params[gadgets.io.RequestParameters.AUTHORIZATION] =
gadgets.io.AuthorizationType.OAUTH;
gadgets.io.makeRequest(url, callback, params);

This way, in each request the OAuth token will be sent to validate the access to the specific resource.

Internationalization
The Gadget API provides you with a simple and easy way to make your applicationss available to international users. You only have to define message bundles that contain the translated strings for each given locale.

Then you have to structure your code to separate specific visible text and replace it with a unique name that will be replaced automatically by the server for each message bundle in the viewer's language. Thus, the gadget gets translated and becomes available to a new bunch of users.

OpenSocial for Container Developers
The Container Development Kit
(Apache Shindig Project) [6]
Shindig is an Apache Software Foundation incubator project and is the reference open source implementation of the OpenSocial specification and Gadgets specification. The main goal of the project is to "Launch a new container in under an hour's worth of work." The architectural components (see Figure 1) of Shindig can be broken down as follows:

• JavaScript Gadget Container: This is the core JavaScript foundation for general gadget functionality. This JavaScript manages security, communication, UI layout, and feature extensions, such as the OpenSocial API.
• OpenSocial Container JavaScript: A simple sample container written in the JavaScript environment that sits on top of the JavaScript Gadget Container and provides OpenSocial specific functionality (profiles, friends, activities, datastore).
• OpenSocial Data Server: The implementation of the server interface to container-specific information, including the OpenSocial REST APIs, with clear extension points so others can connect it to their own back ends.
• Gadget Server: The code used to render the gadget XML into JavaScript and HTML for the container to expose via the container JavaScript that consumes the JSON Wired APIs (< v0.7) or the RESTful APIs (v0.8+).

The first two implementations are language-agnostic, since they are coded in JavaScript + HTML and consume the services that the Data and Gadget servers provide. The last two are coded in Java and PHP.

The Shindig Java and PHP implementations share the same set of features and are mainly a port of each other. For the JavaScript API they also use the same set of libraries. Both are production-ready and running in several containers supporting millions of users.

The adoption of this Apache Foundation open source project decreases the time-to-market of the containers since it has an estimated effort of 10-person years and a robust, scalable, and easy-to-integrate code base. It also leverages the use of Open Standards such as OpenID and OAuth and it has a very strong open source community around it.

These are some Hi5 [7] result numbers.

• Big traffic

-          10k req/sec edge

-          6k req/sec origin

• Akamai caches 75%
• 600+ applications
• Thousands of developers
• 30 billion hits/month
• ... on 40 Shindig Servers

Conclusion
You've seen how to create an application, how to consume services using a RESTful API, and an overview of how OpenSocial Containers are implemented.

What are you waiting for? Grab your favorite text editor and start coding that application you have had in your mind for a long time - there are more than 300 million OpenSocial users willing to use it!

References

1. http://www.opensocial.org/

2. http://code.google.com/apis/opensocial/ zdocs/0.8/reference/

3. http://www.opensocial.org/Technical-Resources/opensocial-spec-v081/restful-

protocol

4. http://www.ietf.org/rfc/rfc4287.txt

5. http://oauth.net/core/1.0/ - OAuth Core 1.0 - Abstract

6. http://incubator.apache.org/shindig/

7. http://sites.google.com/site/io/apache-shindig-make-your-social-site-an-opensocial-container (Slide 46)