OpenSocial and REST/RPC

Overview

Friend Connect supports the OpenSocial REST protocol. OpenSocial REST lets you access OpenSocial data from outside a gadget. For example, you might want to integrate OpenSocial data with an existing sign-in system. This document describes the ways to authenticate REST API calls, and provides sample code you can use when developing your own integration.

• To access data about signed-in users and display that information to your authenticated user, use a site authentication cookie to make OpenSocial API calls. This method is useful if you want to do server-side page generation while while using Friend Connect data to generate targeted pages.
• To access social data for other purposes (for example, background processing), use two-legged OAuth to make your calls. For a full listing of the authentication options available to your website, please see the OpenSocial REST and RPC protocol page.

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
5. Sample code

Using a gadget security token

A gadget security token 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 OpenSocial articles Introduction to Signed Requests and Validating Signed Requests on the OpenSocial site. 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 query parameter.

Example API call:

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

Using standard two-legged OAuth

Standard two-legged OAuth is the best authentication method if you want to do offline processing of visitor data. 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.

The OAuth credentials can be obtained on the Plug-ins and APIs page on the Google Friend Connect admin site.

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

Example API call:

https://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 user, even anonymous ones. If your request requires an established requestor identity (for example, a request for the user me) you must explicitly set the identity of the user who is requesting the data. To do this, set 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:

https://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:

https://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, given the same user ID, will return the same data.

Using the value of the site's authentication cookie

If your site has dynamic content (for example, pages that are generated using PHP), you can write code to extract the fcauth cookie for the current user. Use that cookie to make GFC REST API calls to get the user's profile, friends, and so on.

This authentication method is best if you want to do server-side page generation while 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 expires after a few days.

Example API call:

https://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:

Sample code

Two-legged OAuth

To use two-legged OAuth, you'll need your consumer key and secret, both of which are available on the FriendConnect admin site. Here is a sample API call:

https://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=<your secret>

Authentication with fcauth

The fcauth cookie authentication method is much simpler than OAuth. Copy the fcauth cookie value into the fcauth query parameter for your request, like this:

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

The cookie is long-lived, but does expire after several days.