OpenSocial REST and RPC Protocol

Friend Connect supports the OpenSocial REST protocol. OpenSocial REST lets you access OpenSocial data from outside a gadget. This document describes the ways to authenticate REST API calls.

Contents

1. Using a gadget security token
2. Using standard two-legged OAuth
3. Using the value of the site's authentication cookie
4. Endpoints

Using a gadget security token

This is the best authentication method for gadget developers that want to do much of their programming in a server-side environment, rather than in JavaScript in a gadget.

The gadget security token is a short-lived token that has encoded in it all the necessary information about the site, gadget, and viewer. It can be used to make calls on behalf of the viewer. The gadget security token can be retrieved via JavaScript by doing the following:

var token = shindig.auth.getSecurityToken();

This security token can then be sent to the server via a signed fetch. For more discussion of this topic, see the articles Introduction to Signed Requests and Validating Signed Requests. The server using the security token can then make REST calls to Friend Connect by passing the security token as the value of the st URL parameter.

Example API call:

http://www.google.com/friendconnect/api/people/@owner/@self?st=<your st>

Using standard two-legged OAuth

This is the best authentication method for site owners that want to do offline processing on the members of their community.

The OAuth credentials can be obtained on the "For Site Programmers" page for the site. Two-legged OAuth allows calls that operate as any member of the community, or anonymously. OAuth credentials never expire, though the consumer secret can be reset in the admin pages for the site.

OAuth libraries exist for many popular languages, and make it easier to generate a valid OAuth request.

Example API call:

http://www.google.com/friendconnect/api/people/@owner/@self?oauth_consumer_key=<your
consumer key>&oauth_signature_method=HMAC-SHA1&oauth_timestamp=<the time
right now in millis>&oauth_nonce=<some nonce>&oauth_signature=<signed using your secret>

Note that the previous call fetched the @owner url which in Friend Connect terms represents the current site. This data is accessible by any (even anonymous) users. In the case of a request which requires an established requestor identity (for example, a request for the user @me) you need to explicitly set the identity of the user who is requesting the data. This can be done by setting the xoauth_requestor_id OAuth URL parameter to the id of a site member. If this parameter is omitted or set to empty, the call will execute as an anonymous user.

The following two examples show requesting @me using the xoauth_requestor_id parameter:

http://www.google.com/friendconnect/api/people/@me/@self?xoauth_requestor_id=<ID of the user to fetch>&oauth_consumer_key=<your
consumer key>&oauth_signature_method=HMAC-SHA1&oauth_timestamp=<the time
right now in millis>&oauth_nonce=<some nonce>&oauth_signature=<signed using your secret>

Or just requesting the user's data directly:

http://www.google.com/friendconnect/api/people/<ID of the user to fetch>/@self?oauth_consumer_key=<your
consumer key>&oauth_signature_method=HMAC-SHA1&oauth_timestamp=<the time
right now in millis>&oauth_nonce=<some nonce>&oauth_signature=<signed using your secret>

Either approach is valid and returns the same data, given the same user ID number.

Using the value of the site's authentication cookie

Site owners who have pages that are generated (for example, using PHP) can write code that extracts the fcauth cookie for the current user. They can then use that cookie to make GFC REST API calls to get the user's profile, friends, and so on.

This authentication method is appropriate for site owners that want to do server-side page generation while using Friend Connect data to generate the page. Instead of writing server code to extract the Friend Connect authentication cookie, site owners can simply get the cookie value on requests to their server.

Whenever a user signs into a Friend Connect enabled site, a cookie is placed on the domain of the site. The cookie has the name "fcauth" + <your siteId>. A site owner can set the fcauth URL parameter to the value of this cookie to authenticate OpenSocial REST calls. These calls will be made using the identity of the user whose sign-in generated the cookie.

The cookie is long-lived, but does expire after some number of days.

Example API call:

http://www.google.com/friendconnect/api/people/@owner/@self?fcauth=<your fcauth>

Endpoints

GFC supports the OpenSocial REST and RPC protocols:

• OpenSocial RPC protocol spec
• OpenSocial REST protocol spec

There are also OpenSocial REST/RPC Client Libraries available for many popular programming languages, including Java and PHP.

GFC offers the following endpoints: