An off-site application is an application that runs outside of Orkut and communicates with the platform over HTTP. These applications do not appear in the Orkut directory and users cannot "install" them or add them to their profiles. In fact, users don't need to visit Orkut at all in order to interact with an off-site application: they can interact directly with your site or device.
Orkut currently supports two APIs for off-site applications:
This REST API should not be confused with the Remote API for on-site applications, which is also called "REST" but is not related to this API.
The v1 JSON-RPC API is based on the OpenSocial standard. If you are using the JSON-RPC API with OAuth 1.0, you might be interested in using the Orkut Client Library (Java), which will make your implementation easier.
The REST API makes many new features available to Orkut developers. We will progressively add more features to it, but for now developers will typically use both APIs in conjunction.
Both APIs use OAuth as their authentication mechanism. The v1 JSON-RPC API supports OAuth 1 only, while the v2 REST API supports both OAuth 1.0 and 2.0. Therefore, if you wish to use the same authentication token on both APIs, you should use OAuth 1.0.
The remainder of this page will assume that you will use OAuth 1.0 for both APIs. If, on the other hand, you wish to use OAuth 2.0 for the REST API, you can find more information about it here.
To use OAuth 1.0, you must obtain a key and a secret (called the "consumer key" and "consumer secret"). You can do that by registering your application. Once you have your consumer key and secret, you are ready to write an application for Orkut. The steps involved are:
- Generate a request token.
- Redirect the user to Google to authorize the request token. If the user is not logged in, the login screen will appear before the authorization page.
- Exchange your request token for an access token.
- Issue the API call through HTTP, using the access token to sign the request.
Naturally, once you have the access token, you do not need to execute steps 1 to 3 again: you can just issue other API calls using the same token until it expires or the user revokes it.
If you are unfamiliar with OAuth, please refer to Authentication and Authorization for Google APIs for more details about the process.
Warning: OAuth is the only method your application can use to authenticate with Orkut and users must always type their credentials on the Google authentication page. Prompting for the user's login and password directly is strictly forbidden.
Life of an Off-Site Application
Off-site applications go through a different life cycle than on-site applications. The following list summarizes the main steps involved and highlights the main differences between off-site applications and on-site applications.
- Register your application.. Obtain an OAuth 1.0 consumer key and a consumer secret by registering your web application here. Even if your application is not a web application, you must perform this step using your (or your organization's) domain name. Notice that you must have administrative rights over the domain in order to register, as the registration process will require that you prove that you have control over the domain's configuration.
- Develop your application. There are virtually no restrictions on the environment, language or platform, as long as that platform is able to make OAuth HTTPS requests to the Orkut servers. Since off-site applications do not run in the Orkut interface, you must handle authentication yourself, and that is done through the OAuth protocol.
- Publish your application. Unlike on-site applications, there is no XML to describe the application and it will not appear in the Orkut application directory. Therefore, publishing your application is something you can do entirely on your own: there is no formal process you have to perform on Orkut. Since off-site applications are not listed in Orkut, you must find your own mechanisms to enable users to discover and run your application, whether your application is a website, a mobile application or a cool new embedded device.
- Maintain your application. As users interact with your application, you must continually monitor it to make sure it is always running smoothly, working reliably and that it is not being abused by malicious users or being used in a way that violates the Terms of Service or the Developer Guidelines. Another important point to look out for is to carefully monitor your application to make sure it is not exceeding quota limits for API calls.