Persistence Data API Developer's Guide: Protocol

The OpenSocial Persistence data API allows client applications to view and update OpenSocial Persistence content in the form of AtomPub APIs with a Google data schema. Your client application can create new Persistence entries, edit or delete existing entries, request a list of entires, and query for entries that match particular criteria.

Important: The OpenSocial Persistence data API hasn't been released yet; this document is a preview of the developer's guide that we'll publish when we release the data API. All of the details are subject to change, but this preview should give you a general idea of what the API will be like.

Contents

1. Audience
2. Getting started
3. Authenticating to the OpenSocial Persistence service
   1. AuthSub proxy authentication
   2. ClientLogin username/password authentication
4. Creating Persistence entries
5. Retrieving Persistence entries
   1. Retrieving all Persistence entries
   2. Retrieving Persistence entries using query parameters
6. Updating Persistence entries
7. Deleting Persistence entries

Audience

This document is intended for programmers who want to write client applications that can interact with OpenSocial Persistence. It provides a series of examples of basic data API interactions using raw XML and HTTP, with explanations. After reading this document, you may wish to learn more about interacting with the API using our client libraries by reading the language-specific examples found on the other tabs at the top of this document.

For OpenSocial Persistence data API reference information, see the reference guide.

This document assumes that you understand the general ideas behind AtomPub and the Google data APIs protocol.

If you're using a UNIX system and you want to try this out without writing any code, you may find the UNIX command-line utilities curl or wget useful; for more information, see the manual pages for those utilities.

Getting started

Creating an Orkut account

You may want to sign up for an Orkut account for testing purposes. Orkut uses Google Accounts, so if you already have a Google account, just log in to orkut.com.

Authenticating to the OpenSocial Persistence service

You can access both public and private feeds using the OpenSocial Persistence data API. Public feeds don't require any authentication, but they are read-only. If you want to modify entries then your client needs to authenticate before requesting private feeds. It can authenticate using either of two approaches: ClientLogin username/password authentication or AuthSub proxy authentication.

For more information about authentication with Google data APIs in general, please see the authentication documentation.

AuthSub proxy authentication

AuthSub proxy authentication is used by web applications that need to authenticate their users to Google accounts. The website operator and the client code don't have access to the username and password for the OpenSocial Persistence user; instead, the client obtains special AuthSub tokens that allow the client to act on a particular user's behalf. See the AuthSub documentation for more detailed information.

When a user first visits your application, they have not yet been authenticated. In this case, you need to display some information and a link directing the user to a Google page to authenticate your request for access to their entries.

The AuthSubRequest URL might look like this:

https://www.google.com/accounts/AuthSubRequest?scope=http%3A%2F%2Fsandbox.orkut.com%2Ffeeds%2F&session=1&secure=0&next=http%3A%2F%2Fwww.example.com%2Fwelcome.html

The following query parameters are included in the AuthSubRequest URL:

scope

Indicates that the application is requesting a token to access OpenSocial Persistence feeds.

session

Indicates whether the token returned can be exchanged for a multi-use (session) token.

secure

Indicates whether the client is requesting a secure token.

next

The URL of the page that Google should redirect the user to after authentication.

After the user logs in, the AuthSub system redirects them to the URL you specified in the next query parameter of the AuthSubRequest URL. The AuthSub system appends an authentication token to that URL, as the value of the token query parameter. For example:

http://www.example.com/welcome.html?token=yourAuthToken

This token value represents a single-use AuthSub token. In this example, since session=1 was specified, this token can be exchanged for an AuthSub session token by calling the AuthSubSessionToken service with the single-use token in an Authorization header, as follows, where urlFromAuthSub is the URL that AuthSub appended the token to:

GET /accounts/AuthSubSessionToken HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="yourAuthToken"
User-Agent: Java/1.5.0_06
Host: https://www.google.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
    

The AuthSubSessionToken service response includes a Token header that contains the session token and an Expiration header that indicates how long the token will remain valid. Your application can use the session token value in the Authorization header of subsequent interactions with OpenSocial Persistence. Here's an example of an HTTP request, containing a non-secure token, that you might send to OpenSocial Persistence:

GET /feeds/apps/12345344363/persistence/global HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: AuthSub token="yourSessionToken"
User-Agent: Java/1.5.0_06
Host: sandbox.orkut.com
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
    

ClientLogin username/password authentication

Use ClientLogin authentication if your client is a standalone, single-user "installed" client (such as a desktop application). To request an authentication token using the ClientLogin mechanism, send a POST request to the following URL:

https://www.google.com/accounts/ClientLogin

The POST body should contain a set of query parameters that look like parameters passed by an HTML form, using the application/x-www-form-urlencoded content type. These parameters are:

Email

The user's email address.

Passwd

The user's password.

source

Identifies your client application. Should take the form companyName-applicationName-versionID. The examples use the name exampleCo-exampleApp-1.

service

The OpenSocial Persistence service name is ot. (Other service names are listed here.)

If the authentication request fails, you'll receive an HTTP 403 Forbidden status code.

If it succeeds, then the response from the service is an HTTP 200 OK status code, plus three long alphanumeric codes in the body of the response: SID, LSID, and Auth. The Auth value is the authorization token that you'll send to OpenSocial Persistence with your request, so keep a copy of that value. You can ignore the SID and LSID values.

Since all requests to private feeds require authentication, you have to set the Authorization header in all subsequent interactions with OpenSocial Persistence, using the following format:

Authorization: GoogleLogin auth=yourAuthToken

Where yourAuthToken is the Auth string returned by the ClientLogin request.

For more information about ClientLogin authentication, including sample requests and responses, see the Account Authentication for Installed Applications documentation.

Creating Persistence entries

Once the client has been authenticated you can use it to publish Persistence entries.

First, create an XML representation of the key/value pair to publish. This XML needs to be in the form of an Atom <entry> element, with the key in the atom:title and the value in the atom:content which might look something like this:

<entry xmlns='http://www.w3.org/2005/Atom'>
<title type="text">somekey</title>
<content type="text">somevalue</content>
</entry>

To publish this entry, post it to one of the Persistence feeds as follows. First, place your Atom <entry> element in the body of a new POST request, using the application/atom+xml content type. For example

http://sandbox.orkut.com/feeds/app/1234567/persistence/global

OpenSocial Persistence creates an new key/value entry post using the entry you sent, then returns an HTTP 201 CREATED status code, along with a copy of the new post in the form of an <entry> element. The entry returned is the same one you sent, but it also contains various elements added by OpenSocial Persistence, such as an <id> element.

If your request fails for some reason, OpenSocial Persistence may return a different status code. For information about the status codes, see the protocol reference document.

Retrieving Persistence entries

Retrieving all Persistence entries

The general idea of how to retrieve posts is to request a OpenSocial Persistence feed by sending an HTTP GET request to the Persistence entries feed URL. OpenSocial Persistence then returns a feed containing the appropriate key/value entries. To get the feed of an applications global entries, you send the following HTTP request to OpenSocial Persistence (with the appropriate value in place of applicationID, of course):

GET /feeds/apps/applicationID/persistence/global

OpenSocial Persistence then returns an HTTP 200 OK status code and a standard Atom 1.0 feed containing all the posts in the applications global data. The following is an example of a feed for an applications global data with only one entry.

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'>
<id>http://sandbox.orkut.com:80/feeds/apps/02864641990088926753/persistence/global</id>
<updated>2007-10-30T20:53:20.086Z</updated>
<title>Persistence</title>
<link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://sandbox.orkut.com:80/feeds/apps/02864641990088926753/persistence/global'/>
<link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml' href='http://sandbox.orkut.com:80/feeds/apps/02864641990088926753/persistence/global'/>
<link rel='self' type='application/atom+xml' href='http://sandbox.orkut.com:80/feeds/apps/02864641990088926753/persistence/global'/>
<generator version='1.0' uri='/feeds'>Orkut</generator>
<entry>
  <id>http://sandbox.orkut.com:80/feeds/apps/02864641990088926753/persistence/global/somekey</id>
  <title>somekey</title>
  <content>somevalue</content>
  <link rel='self' type='application/atom+xml' href='http://sandbox.orkut.com:80/feeds/apps/02864641990088926753/persistence/global/somekey'/>
  <link rel='edit' type='application/atom+xml' href='http://sandbox.orkut.com:80/feeds/apps/02864641990088926753/persistence/global/somekey'/>
</entry>
</feed>
    

Retrieving Persistence entries using query parameters

The Google data API lets you request a set of entries that match specified criteria, such as requesting Persistence entries with a specific key

For example, to send a key query, add the key parameter to the request URL for friends data. To get all the Persistence entries for a users friends with the key 'somekey' for a given application, send an HTTP request to the users friends data feed URL (with the appropriate values in place of applicationID and userID, of course):

GET /feeds/apps/applicationID/persistence/userID/friends?key=somekey

After you send the GET request, OpenSocial Persistence may return a redirect, depending on various factors. If so, send another GET request to the redirect URL.

When you send that GET request, OpenSocial Persistence returns an HTTP 200 OK status code and a feed containing any Persistence entry posts that have the key specified for all of a users friends.

The OpenSocial Persistence data API supports the following query parameters:

alt

The type of feed to return, such as atom (the default) or rss.

key

Only supported on the friends data feed

Note that this service does not support common Google data API query parameters such as full-text search.

For more information about query parameters, see the OpenSocial Persistence Data API Reference Guide and the Google Data APIs Reference Guide.

Note: The entries in a feed are arbitrarily ordered.

Updating Persistence entries

To update an existing Persistence entry, send a PUT request with the updated entry in the message body to the post's edit URL. Be sure that the <id> value in the entry you POST exactly matches the <id> of the existing entry. The edit URL is highlighted in the following post entry:

<entry>
  <id>http://sandbox.orkut.com:80/feeds/apps/02864641990088926753/persistence/global/somekey</id>
  <title>somekey</title>
  <content>somenewvalue</content>
  <link rel='self' type='application/atom+xml' href='http://sandbox.orkut.com:80/feeds/apps/02864641990088926753/persistence/global/somekey'/>
  <link rel='edit' type='application/atom+xml' href='http://sandbox.orkut.com:80/feeds/apps/02864641990088926753/persistence/global/somekey'/>
</entry>
    

IMPORTANT! To ensure forward compatibility, be sure that when you POST an updated entry you preserve all the XML that was present when you retrieved the entry from OpenSocial Persistence. Otherwise, when we implement new stuff and include <new-awesome-feature> elements in the feed, your client won't return them and your users will miss out! The Google data API client libraries all handle this correctly, so if you're using one of the libraries you're all set.

Troubleshooting Tip: Some firewalls block HTTP PUT messages. To get around this you can include the X-HTTP-Method-Override: PUT header in your requests.

Deleting Persistence entries

To delete an Persistence entry, send a DELETE request to the entry's edit URL. This is the same URL used to update the entry.

Troubleshooting Tip: Some firewalls block HTTP DELETE messages. To get around this you can include the X-HTTP-Method-Override: DELETE header in your requests.

Back to top