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 AudienceThis 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 Getting startedCreating an orkut sandbox accountBefore you can use this API, you should sign up for an orkut sandbox account. About data formatsData 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 typesThe REST API provides three types of data items, two of which are currently supported by orkut:
About applications and home serversThis 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 OAuthOAuth 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 secretTo 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 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 requestsTo 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.
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 Managing Person itemsAfter 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 itemsThe following sections describe how to retrieve a collection of Person items, with and without query parameters. Retrieving the user's Person itemTo retrieve a user's Person item, send an authenticated HTTP 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 contactsYou 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 http://www.orkut.com/social/rest/people/userID/@friends To retrieve a list of all of a user's contacts, send a 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 { "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 itemsThe 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 GET http://www.orkut.com/social/rest/people/userID/@friends?count=5 When you send that 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):
For more information about query parameters, see the query parameters section of the OpenSocial REST API specification. Managing AppData itemsAfter 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 itemsFirst, 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 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 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 itemsThe following two sections describe how to retrieve a collection of AppData items, with and without query parameters. Retrieving all AppData itemsTo retrieve the user's AppData items, send an HTTP 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 On receiving the request, orkut returns an HTTP 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 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 itemsThe 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:
For more information about query parameters, see the query parameters section of the OpenSocial REST API specification. Updating AppData itemsTo 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 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 You can't update data for multiple people at once using a selector—for example, you can't send a Troubleshooting Tip: Some firewalls block HTTP Deleting AppData itemsTo delete an AppData item, send an authenticated Troubleshooting Tip: Some firewalls block HTTP Note: To update existing AppData items, see Updating AppData items; don't update by deleting AppData items and then re-adding them. |