The Base Data API allows client applications to view and update the items stored in your Google Base account in the form Google Data API feeds.
Your application can use the Base Data API to create new items, edit or delete existing items, and query for items and/or metadata that match particular criteria.
In addition to providing some background on the capabilities of the Base Data API, this document provides examples of basic Data API interactions using the JavaScript client library. If you're interested in understanding more about the underlying protocol that the library uses, see the Developer's Guide.
This document is intended for programmers who want to write JavaScript client applications that can interact with your Google Base items. It provides a series of examples of basic Base Data API interactions using the JavaScript client library.
For Base Data API reference information, see the reference guide. This document assumes that you understand the general ideas behind the Google Data APIs protocol and the data model and control flow used by the JavaScript client library. It also assumes that you know how to program in JavaScript.
For reference information about the classes and methods provided by the client library, see the JavaScript client library API reference.
This document is designed to be read in order; each example builds on earlier examples.
You agree to abide by the Google JavaScript client library Terms of Use when using the JavaScript client library.
Currently, we only support JavaScript client applications that run in a web page in a browser. Currently supported browsers are:
The JavaScript client library handles all communication with the Base API server. If you're an experienced JS developer, you may be thinking, "But what about the same origin policy?" The JavaScript client library allows your client to send Google Data API requests from any domain while remaining compliant with the browser security model.
Before you can write a JavaScript client application, you need to do some setup by acquiring the library.
You may want to sign up for a Google Account for testing purposes. Google Base accounts are associated with your Google Accounts, so if you already have a Google Account, you're all set.
Note: To view and manage your items without using the Base Data API, you can log in to your Google Base Dasboard.
Before your client can use the client library, the client has to request the client library code from the server.
Start by using a <script> tag in the <head> section of your HTML document to fetch the Google AJAX API loader:
<script type="text/javascript" src="http://www.google.com/jsapi"></script>
To acquire the Google Data JavaScript client library after fetching the loader, use the following line in your setup code, which must be called from the <head> section of your HTML document
(or from a JavaScript file that's included using a <script> tag in the <head> section of your HTML document):
google.load("gdata", "1.x");
The second parameter to google.load() is the requested version number of the JavaScript client library. Our version numbering scheme is modeled after the one used by the Google Maps API. Here are the possible version numbers and what they mean:
"1""1.x""1.s""1.0", "1.1", etcAfter you've called google.load(), you have to tell the loader to wait until the page finishes loading and then call your code:
google.setOnLoadCallback(initFunc);
Where initFunc() is a function that we'll define in a later section of this document. Use this approach instead of having an onload handler attached to the <body> element.
You can access both public and private feeds using the Base Data API. Public feeds don't require any authentication, but they are read-only. If you want to modify items or upload new ones, your client needs to authenticate before requesting private feeds.
The JavaScript client library uses the AuthSubJS, an flavor of the AuthSub authentication system. For more information about authenticating your JavaScript clients with Google Data APIs, see the AuthSubJS documentation.
AuthSubJS proxy authentication is used by JavaScript applications that need access to a user's Google data. The website operator and the client code don't have access to the username and password for the user; instead, the client obtains special AuthSub tokens that allow the client to act on a particular user's behalf.
Here's a brief overview of what happens during the authorization process for a web-based JavaScript client:
google.accounts.user.login() method provided by the client library, passing it a "scope" value that indicates which Google service to use. For Google Base, the scope is "http://www.google.com/base/feeds".google.accounts.user.login().Note: For the JavaScript client library to make authenticated Base API requests in a web browser, your page must contain an image that's hosted at the same domain as your page. It can be any image, even a single-pixel transparent image, but
there must be an image on the page. If you want the image to not appear on your page, you can use the style attribute of the <img> tag to position the image outside the rendering area. For example: style="position:absolute; top: -1000px;"
Here's the client-application code that handles logging and creates a connection (represented by a google.gdata.gbase.GoogleBaseService object) to Google Base.
var baseService;
function setupBaseService() {
baseService = new google.gdata.gbase.GoogleBaseService('GoogleInc-basejsguide-1.0');
}
function logMeIn() {
var scope = 'http://www.google.com/base/feeds';
var token = google.accounts.user.login(scope);
}
function initFunc() {
setupBaseService();
logMeIn();
getMyItems();
}
Note that we're making baseService a global variable, for ease of use in later functions. We'll define the function getMyItems() below.
Tip: We strongly recommend that you provide a login button or other user input mechanism to prompt the user to start the login process manually.
If you call google.accounts.user.login() immediately after the page is loaded, then the first thing the user sees on arrival to your site is a Google login page.
If the user decides not to log in, then Google does not direct them back to your page; so from the user's point of view, they tried to visit your page but were sent away and never
sent back. This scenario may be confusing and frustrating to users. In the example code in this document, we'll be calling google.accounts.user.login() immediately after loading in order to keep the example simple,
but we don't recommend this approach for real-world client applications.
Note that you don't have to do anything with the variable named token; the client library keeps track of the token, so you don't have to.
Note: When you create a new google.gdata.gbase.GoogleBaseService object, the client library calls a method named google.gdata.client.init(), which checks that the browser the client is
running in is supported. If there's an error, then the client library displays an error message to the user. If you want to handle this sort of error yourself, then you can
explicitly call google.gdata.client.init(handleInitError) before you create the service, where handleInitError() is your function. If an init error occurs, then your function receives a standard Error object; you can do whatever you want with that object.
The token remains valid until you revoke it by calling google.accounts.user.logout():
function logMeOut() {
google.accounts.user.logout();
}
If you don't call google.accounts.user.logout(), then the cookie that stores the token lasts for two years, unless the user deletes it. The cookie is retained across browser sessions, so the user can close their browser and then reopen
it and come back to your client and they'll still be logged in.
However, there are certain unusual circumstances in which a token can become invalid during a session. If the Base API rejects a token, your client should handle the error condition by calling google.accounts.user.logout() to remove the cookie containing the current token,
and then call google.accounts.user.login() again to acquire a new, valid token.
There are two other AuthSub methods that you may find useful in various contexts:
google.accounts.user.checkLogin(scope) tells you whether or not the browser currently has an authentication token for the given scope.google.accounts.user.getInfo() provides detailed information about the current token, for debugging use.For details about using JavaScript to interact with AuthSubJS, including information on token management and on checkLogin() and getInfo(), see the Using "AuthSub" Authentication with the JavaScript client library document.
The Base Data API provides a feed that returns a list of items for a particular user; that feed is known as the items feed.
The following sample code defines the getMyItems() function and the callback needed to process the
resulting feed:
function getMyItems() {
var itemsFeedUri = 'http://www.google.com/base/feeds/items';
var query = new google.gdata.gbase.ItemsQuery(itemsFeedUri);
// Set the maximum of the result set to be 25
query.setMaxResults(25);
baseService.getItemsFeed(query, handleItemsFeed, handleError);
}
var handleItemsFeed = function(result) {
var entries = result.feed.entry;
for (var i = 0, item; item = entries[i]; ++i) {
alert(item.getTitle().getText());
}
}
Note that baseService is our global variable from earlier.
The specified itemsFeedUri variable is the default items feed URL; it allows you to work with the authenticated user's items.
After setting up the service, getMyItems() calls the client library's getItemsFeed() method which returns the user's items feed as a json object.
In the call to getItemsFeed(), the second argument is handleItemsFeed, which is a callback function. The API processes the request and then, if the request was successful, passes a "feed root" object containing
the requested feed to the callback. A feed root is a container object that contains a feed.
The third argument to getItemFeed() is an optional error-handling function; if the client library encounters an error, it calls the specified error handler instead of the success callback function.
The object that the client library passes as the argument to the error handler is an instance of the JavaScript Error object, with an additional cause property.
Here's a simple version of the error handler:
function handleError(e) {
alert("There was an error!");
alert(e.cause ? e.cause.statusText : e.message);
}
We're handling errors by simply displaying them to the user; your client's error handler should probably be more sophisticated. In some contexts, there may be no cause specified, so in those cases our example error handler falls back to displaying the standard message property.