iGoogle (Deprecated)

OpenSocial REST and RPC Protocol

Important: iGoogle will be retired on November 1, 2013. We are no longer accepting new gadget submissions, but you can still update your previously submitted gadgets.

The OpenSocial REST protocol on iGoogle lets you access OpenSocial data stored outside a gadget. This document describes the ways to authenticate REST API calls.

Contents

  1. Using two-legged OAuth
  2. Using three-legged OAuth
  3. Endpoints

Using two-legged OAuth

This is the best authentication method for gadget authors that want to do offline processing on the users of their gadget.

The OAuth credentials can be obtained on the gadget registration page. Two-legged OAuth allows calls that operate as any user of the gadget. OAuth credentials never expire, and are tied to the URL for the gadget. If a gadget is aliased, new credentials must be obtained.

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

Example API call (with added spacing for clarity):

http://www-opensocial.googleusercontent.com/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>

Note that the previous call fetched the @me url which in iGoogle terms represents the current user. Since @me requires an established requestor identity 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 the desired user.

Alternatively, you can request the user's data directly:

http://www-opensocial.googleusercontent.com/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. See section 2.1 of the REST protocol spec for example responses.

Using three-legged OAuth

This is the best authentication method for gadget authors that want to consume social data outside of Google containers.

The OAuth credentials can be obtained on the web-app registration page. Three-legged OAuth allows calls that operate on behalf of the current user.

The process for obtaining the required per-use access token (the OAuth dance) is described in detail here. iGoogle requires that the scope be set to http://www-opensocial.googleusercontent.com/api when using three-legged OAuth.

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

Once the access token is obtained, the requests are largely similar, with the notable addition of the oauth_token parameter, and the exclusion of the xoauth_requestor_id parameter (since three-legged OAuth inherently provides a user scope). Example API call:

http://www-opensocial.googleusercontent.com/api/people/@me/@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>&
  oauth_token=<the retrieved OAuth token>

Endpoints

iGoogle supports the OpenSocial REST and RPC protocols:

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

iGoogle offers the following endpoints:

API Endpoint Supported Operations
People REST http://www-opensocial.googleusercontent.com/api/people/ GET
Activity REST http://www-opensocial.googleusercontent.com/api/activities/ GET, POST, DELETE, PUT
AppData REST http://www-opensocial.googleusercontent.com/api/appdata/ GET, POST, DELETE, PUT
All RPC http://www-opensocial.googleusercontent.com/api/rpc POST

 

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.