Server to Server Protocol

Platforms / Frameworks / Libraries‎ > ‎OpenSocial‎ > ‎orkut Developer Documentation‎ > ‎

Server to Server Protocol

The OpenSocial REST API for orkut allows an application's home server to view and publish data on behalf of users of that application.

Your server can use 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.

Although orkut supports the RPC protocol, this document does not cover that protocol. For information about that protocol, see the RPC protocol specification. The RPC endpoint for orkut is http://www.orkut.com/social/rpc/.

Audience

This document is intended for programmers who want to write code to interact with orkut using HTTP and JSON.

This document assumes that you understand the general idea of a REST API, and that you're familiar with the orkut GUI.

If you're using a UNIX system and you want to try the examples in this document 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 sandbox account

Before you can use this API, you should sign up for an orkut sandbox account.

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.

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. In orkut, only two-legged OAuth is supported, so that's what this document covers.

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 shared secret

To acquire a shared secret for your application, visit the Gadget Ownership Verification page and enter the URL of your application's XML file.

The verification system needs to verify that you control the application, so it provides you with a token in the form of a comment string. You add that comment string to the CDATA section of your XML file, then click the Verify button. The system requests your XML file again and verifies that you've added the comment to it.

Having verified that you're the application's developer, the system provides you with two more tokens: an OAuth Consumer Key and an OAuth Consumer Secret (also known as a "shared secret"). Your home server must use these tokens to create all authenticated requests it sends to orkut.

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.

Comments

programming

Navigation

Recent site activity