The Google API and Using Web Services

Overview

Accessing a given web service can be kind of a pain. One of the biggest issues is that service providers don't always document APIs as well as they should. In many cases, you'll simply find a web page that contains several examples of HTTP GET or PUT/POST requests and the responses you would expect to receive from the server. As a result, using web services can involve a significant amount of trial and error.

It is also fairly common for providers of web services to provide client libraries, which are easier to use. These libraries typically come in many flavors (Java, python, ruby) and provide a series of method calls for you to perform the necessary functions. For your lab assignment, you will NOT be using a client library. For full credit, you are required to use the RESTlet client and HTTP.

You will be using the Google Documents List Data API, which enables you to access your Google Documents information. For now, you will only need to know how to upload a new document to your Docs account and retrieve a list of documents in a given account. For Project 3, you may choose to extend your Booksite to provide more integration with Google/Google Docs.

Authentication

The first step to using the Google API (and many other APIs as well) is to authenticate your client. There are a couple of ways to do this. If you are writing what Google refers to as a 'Single-user "installed"' application, your application can get the username/password and authenticate with the Google server. In our case, however, we'll use the "Multiple-user web application" approach. This approach works as follows:

  1. A user visits a web page on your site. This page contains a link to https://www.google.com/accounts/AuthSubRequest containing several parameters. One of those parameters ("next") is the page where the user should be redirected once he/she has authenticated with Google.
  2. When the user clicks the link, he/she goes to the Google login page and uses his/her Google username/password to log in. The user is then prompted to grant permission to your application (the booksite) to access Google services on your behalf.
  3. Once the user grants permission, he/she is redirected to the page you specified in the next parameter. When this page is requested, a one-use token is passed as a parameter in the URL.
  4. Your server extracts the token from the URL and uses it to make another request to Google to upgrade to a session token. Your server sends a GET to /accounts/AuthSubSessionToken and receives a token in the text of the reply. Your server extracts that token and uses it in subsequent requests in the Authentication header.
  5. The RESTlet Client uses the ChallengResponse to set the Authentication header in a request. For each request, you'll need to set the ChallengeResponse to the be the appropriate authentication header (containing the token). Also, when you set the ChallengeScheme, you'll need to create a new ChallengeScheme passing the empty string as the value for both parameters the constructor expects.

Uploading Documents

To upload documents you do not need to use Atom. All you need to do send a POST where the body of your POST request contains your document and you send a Slug header that contains the name you wish to give the document (presumably the title of the book). You will need to read the RESTlet documentation to figure out how to set a special header for your POST request.

Sami Rollins

Date: 2008-02-21