Orkut Application Platform

On-Site Application Developer Guide: Remote API

This section presents the REST-based Remote API for on-site gadgets, not to be confused with the JSON-RPC protocol used by off-site applications over 3-legged OAuth.

This API allows an application's home server to view and publish data on behalf of users of that on-site application (but does not allow you to access Orkut when the user is "offline", that is, not running that particular on-site application). If you want to make requests to Orkut outside the context of a currently running on-site application, you probably want to write an off-site application instead.

Your server can use this remote API (based on the OpenSocial REST API) to retrieve Person items from Orkut (including retrieving a list of a given user's friends) and create, retrieve, update, and delete AppData items.

In addition to providing some background on the capabilities of Orkut's implementation of the OpenSocial REST API, this document provides examples of basic REST API interactions using HTTP and JSON.

Note: Orkut currently supports only a subset of the OpenSocial REST API. Any REST API features not documented here are not supported by Orkut.

For more information about the OpenSocial REST API, see the REST protocol specification.

Contents

Getting started

About data formats

Data provided by the REST API takes the form of a collection of items. Such a collection can be represented in various formats; in particular, OpenSocial collections can take the form of JSON objects, Atom feeds, or non-Atom XML data.

However, Orkut currently supports only the JSON format.

(The Atom and XML formats are available, but not currently officially supported.)

About OpenSocial data types

The REST API provides three types of data items, two of which are currently supported by Orkut:

Person
Information about a person. A collection of these items represents a group of people, such as a given user's friends.
AppData
An item of data, such as a preference setting, stored by Orkut on a user's behalf for a given application. A collection of these items might be the whole set of preferences for the application.

About applications and home servers

This guide assumes that your REST API interaction will be between your home server (the server where you store data and code and user information and so on) and Orkut. Your application, running in a user's browser window, may also communicate with Orkut, but we assume that it will use means other than the REST API to do so. Therefore, this guide focuses on the use case in which your home server is sending REST API requests to Orkut, on behalf of your application's users.

For example, your home server might use the REST API to update your application's AppData on Orkut for a given user on that user's birthday, even if the user isn't logged in. Or your home server could use the REST API to find the top ten scores for your game among all of your users, where scores are stored as AppData on Orkut.

Using the REST API, your server can access the profile information, friends list, or AppData for any user that has installed your application, since these users agreed to grant your application access to their data when they installed the application. In the authentication section of this document, below, you'll learn how to sign your requests so that Orkut knows the request came from your server and can check to see if you have access to the data you're requesting. Note that Orkut keeps track of which users have installed your application.

Note: Your home server can use the REST API to communicate with Orkut only if Orkut users are using your application, within Orkut. If you don't provide an application/gadget for use within Orkut, then your server can't interact with Orkut using the REST API. If you want to interact with Orkut without an associated on-site application, what you probably want to write is an off-site application instead.

Authenticating with OAuth

OAuth is an open protocol that allows API calls to be authorized and authenticated. Use OAuth authentication to allow your application's home server to do authenticated communication with Orkut.

Every request sent using this API must be accompanied by OAuth authentication parameters.

Most of the samples in subsequent sections of this document assume you're supplying the appropriate authentication, if needed.

There are two varieties of OAuth: two-legged OAuth and three-legged OAuth. This Remote API for on-site gadgets uses 2-legged OAuth, unlike the API for off-site applications, which uses 3-legged OAuth.

For more detailed information about two-legged OAuth and use cases in OpenSocial, see 2-legged OAuth for the OpenSocial REST API. For information about OAuth in general, see the OAuth Getting Started guide.

Before you can use OAuth, you have to acquire a shared secret for your application. This is a value that Orkut provides you with, unique to your application, that helps authenticate requests from your home server.

When you want to send an authenticated request from your home server to Orkut, you append various OAuth query parameters to the URL. The query parameters let Orkut determine that the request really is coming from your server.

Acquiring a Consumer Key and Secret

The consumer key and consumer secret used with this API are the ones you obtain when you submit your application through the Developer Page. These are not the ones you obtain from Google when you register your web application's domain (that consumer key and secret are for 3-legged OAuth for off-site applications, which is a different API).

Authenticating requests

To send an authenticated request to Orkut from your home server, first generate a signature for the request, then send the request to the appropriate Orkut URL, specifying the following URL parameters.

Note: You have to provide all of these query parameters with every request you send to Orkut; in this use of OAuth, you don't get a reusable authentication token.

oauth_consumer_key
The consumer key that you acquired when you verified ownership. (Note: don't send the shared secret, only the consumer key.)
oauth_nonce
The nonce: a random string. Generate a new unique random nonce for each request.
oauth_signature
The signature, which your home server must generate using the shared secret and the specified signature method.
oauth_signature_method
The signature method you used to sign the request. Value must be HMAC-SHA1.
oauth_timestamp
The request's timestamp.
oauth_version
The version of OAuth that you're using. Value must be 1.0.
xoauth_requestor_id
The Orkut user ID of the user who has the application installed, on whose behalf you're sending this request. (Optional if you specify a user ID in requests; required if you specify @me.)

On receiving the request, Orkut verifies the signature; if the authentication succeeds, it allows the request. If the authentication fails—for example, if the signature is wrong, or if you're trying to access information for a user who hasn't installed your application—then Orkut responds with an HTTP 401 Unauthorized status code.

Managing Person items

After authenticating, you can retrieve Person items.

A Person item, also called a Person, contains a person's profile details.

A Person collection lists the Person items relevant to the user.

Retrieving Person items

The following sections describe how to retrieve a collection of Person items, with and without query parameters.

Retrieving the user's Person item

To retrieve a user's Person item, send an authenticated HTTP GET request to the following URL:

http://www.orkut.com/social/rest/people/userID/@self

Replace userID with the user ID of any user who has installed your application.

On receiving the request, Orkut returns a Person item like the following:

{
  "entry": {
    "photos": [
      {
        "value": "http://www.orkut.com/img/i_nophoto64.gif",
        "type": "thumbnail"
      }
    ],
    "id": "userID",
    "thumbnailUrl": "http://www.orkut.com/img/i_nophoto64.gif",
    "name": {
      "familyName": "Bennet",
      "givenName": "Elizabeth"
    }
  }
}

Retrieving the user's contacts

You can retrieve a list of a user's friends, or a list of all of their contacts.

To retrieve a list of a user's friends, send a GET request to the following URL:

http://www.orkut.com/social/rest/people/userID/@friends

To retrieve a list of all of a user's contacts, send a GET request to the following URL:

http://www.orkut.com/social/rest/people/userID/@all

Replace userID with the user ID of any user who has installed your application.

In either case, Orkut returns an HTTP 200 OK status code and a collection containing Person items, one for each of the user's friends or contacts. For example, if the user has only one friend, the friends collection might look like the following. We've slightly edited this example to make it a little more readable by humans; in particular, a real OpenSocial collection contains actual user IDs.

{
  "startIndex": 0,
  "totalResults": 1,
  "entry": [
    {
      "photos": [
        {
          "value": "http://www.orkut.com/img/i_nophoto64.gif",
          "type": "thumbnail"
        }
      ],
      "id": "friend1UserID",
      "thumbnailUrl": "http://www.orkut.com/img/i_nophoto64.gif",
      "name":
        {
          "familyName": "Bennet",
          "givenName": "Jane"
        }
    }
  ]
}

For information about what each of those attributes means, see the OpenSocial REST API specification.

If your request fails for some reason, Orkut may return a different status code. For information about HTTP status codes, see the status codes section of the REST API specification.

Filtering, sorting, and paginating Person items

The OpenSocial REST API lets you specify various criteria to apply to the returned collection, such as requesting that only a particular set of fields be returned for each Person in the collection, or requesting that only results that match a particular field value be returned.

For example, to request only the first "page" of a user's friends, add the count parameter and a page size to the request URL:

GET http://www.orkut.com/social/rest/people/userID/@friends?count=5

When you send that GET request, Orkut returns an HTTP 200 OK status code and a collection of Person items sorted by date.

To request all of a user's friends who have your application installed, send this request:

GET http://www.orkut.com/social/rest/people/userID/@friends?filterBy=hasApp&filterOp=equals&filterValue=true

The OpenSocial REST API supports the following query parameters (the same parameters supported by the JavaScript API):

count
The number of items per page, for a paged collection. The default value is 20.
fields
Comma-separated list of fields to include in the representation.
filterBy
Field name to filter on, using the operation and value specified in filterOp and filterValue.
filterOp
Operation to use when filtering by field.
filterValue
Value to use when filtering by field.
startIndex
The 1-based index of the first result to be retrieved (for paging).

For more information about query parameters, see the query parameters section of the OpenSocial REST API specification.

Managing AppData items

After authenticating, you can publish and retrieve AppData items.

An AppData item is an item of data, such as a preference setting, stored by Orkut on the user's behalf.

An AppData item collection lists the AppData items relevant to the user.

Creating AppData items

First, create a JSON representation of the AppData item to publish. The JSON code might look like this:

{
  "letters": 3,
  "last_letter_date": "2008-10-30T18:30:02Z"
}

To publish this entry, first place your JSON code in the body of a new POST request, using the application/json content type. Then post the request to the following URL, with appropriate authentication:

 http://www.orkut.com/social/rest/appdata/userID/@app

On receiving the request, Orkut creates an AppData item using the entry you sent, then returns an HTTP 201 Created status code, along with a copy of the new AppData item. The AppData item returned is the same one you sent, but it also contains some information generated and added by Orkut.

If your request fails for some reason, Orkut may return a different status code. For information about HTTP status codes, see the status codes section of the REST API specification.

Retrieving AppData items

The following two sections describe how to retrieve a collection of AppData items, with and without query parameters.

Retrieving all AppData items

To retrieve the user's AppData items, send an HTTP GET request to the AppData item URL. On receiving the request, Orkut returns a collection of the appropriate AppData items. For example, to get a list of your application's AppData items for a user, send the following HTTP request to Orkut (with the appropriate value in place of selector):

GET http://www.orkut.com/social/rest/appdata/userID/selector/@app

Replace userID with the user ID of any user who has installed your application.

The selector value can be @self for the user's own AppData, @friends for the user's friends' AppData, or @all for all of the AppData belonging to all of the user's contacts.

On receiving the request, Orkut returns an HTTP 200 OK status code and a collection containing the AppData items, in JSON format.

The following is an example of an AppData items collection for a user's friends.

{
  "entry": {
    "10459228050876679741": {
      "letters": "2",
      "last_letter_date": "2008-10-15T10:01:00Z"
    },
    "07365476160138082838": {
      "letters": "1",
      "last_letter_date": "2008-09-28T08:20:20Z"
    }
  }
}

Note that a single AppData entry object can contain AppData for multiple users, and there can be multiple pieces of data for each user.

For information about the structure of an entry, see the OpenSocial REST API specification.

If your request fails for some reason, Orkut may return a different status code. For information about HTTP status codes, see the status codes section of the REST API specification.

Filtering AppData items

The OpenSocial REST API lets you request that only a particular set of fields be returned for each AppData item in the collection. To make such a request, use the following query parameter:

fields
Comma-separate list of fields to include in the representation.

For more information about query parameters, see the query parameters section of the OpenSocial REST API specification.

Updating AppData items

To update an existing AppData item, first you retrieve the AppData item you want to update, then you modify it, and then you send an authenticated PUT request, with the updated data in the request body, to the AppData item's URL.

For example, say you've retrieved the following AppData item:

{
  "entry": {
    "15913663323317925521": {
      "letters": "3",
      "last_letter_date": "2008-10-30T18:30:02Z"
    }
  }
}

You might modify it as follows:

{
  "entry": {
    "15913663323317925521": {
      "letters": "4",
      "last_letter_date": "2008-10-31T20:20:01Z"
    }
  }
}

Then use PUT to send the new AppData item to the AppData item URL. On receiving the request, Orkut replaces the original AppData item with the newly modified one.

You can't update data for multiple people at once using a selector—for example, you can't send a PUT request to .../appdata/userID/@friends/@app. You have to update each friend separately.

Troubleshooting Tip: Some firewalls block HTTP PUT messages. To get around this, you can include an X-HTTP-Method-Override: PUT header in a POST request.

Deleting AppData items

To delete an AppData item, send an authenticated DELETE request to the AppData item's URL.

Troubleshooting Tip: Some firewalls block HTTP DELETE messages. To get around this, you can include an X-HTTP-Method-Override: DELETE header in a POST request.

Note: To update existing AppData items, see Updating AppData items; don't update by deleting AppData items and then re-adding them.

Back to top

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.