The Blogger Data API allows client applications to view and update Blogger content in the form of Google Data API feeds.
Your client application can use the Blogger Data API to create new blog posts, edit or delete existing blog posts, and query for blog posts that match particular criteria.
In addition to providing some background on the capabilities of the Blogger 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 Protocol section of this developer's guide.
Contents
Audience
This document is intended for programmers who want to write JavaScript client applications that can interact with Blogger. It provides a series of examples of basic Data API interactions using the JavaScript client library.
For Blogger Data API reference information, see the Protocol 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.
Terms of use
You agree to abide by the Google JavaScript Client Library Terms of Use when using the JavaScript client library.
About supported environments
Currently, we only support JavaScript client applications that run in a web page in a browser. Currently supported browsers are Firefox 1.5 and higher, and Internet Explorer 6.0 and higher.
The JavaScript client library handles all communication with the service's 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.
Getting started
Before you can write a JavaScript client application, you need to do some setup to acquire the library.
Creating a Blogger account
You may want to sign up for a Blogger account for testing purposes. Blogger uses Google Accounts, so if you already have a Google account, you're all set.
Acquiring the library
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="https://www.google.com/jsapi"></script>
To acquire the Google Data API client library after fetching the loader, use
the following line in your JavaScript 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"
- The second-to-last revision of major version 1.
"1.x"
- The very latest revision of major version 1.
"1.s"
- The latest stable revision of major version 1. We will occasionally declare a certain version of the client library to be "stable," based on feedback we receive from developers. However, that version may not have the latest features.
"1.0"
,"1.1
", etc- A specific version of the library, with a specified major and minor revision number.
After 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(getMyBlogFeed);
Where getMyBlogFeed()
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.
Authenticating to the Blogger service
You can access both public and private feeds using the Blogger Data API. Public feeds don't require any authentication, but they are read-only. If you want to modify blogs, then your client needs to authenticate before requesting private feeds.
The JavaScript client library uses the AuthSub authentication system. For more information about authentication with Google Data APIs in general, see the authentication documentation.
AuthSub proxy authentication
AuthSub proxy authentication is used by web applications that need to authenticate their users to Google Accounts. The website operator and the client code don't have access to the username and password for the Blogger 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 authentication process for a web-based JavaScript client:
- The client application calls the
google.accounts.user.login()
method provided by the client library, passing it a "scope" value that indicates which Google service to use. For Blogger, the scope is"http://www.blogger.com/feeds/"
. - The client library sends the browser to Google's "Access Request" page, where the user can enter their credentials to log in to the service.
- If the user logs in successfully, then the AuthSub system sends the browser back to the web client's URL, passing along the authentication token.
- The JavaScript client library stores the token in a cookie and returns
control to the client application's function that called
google.accounts.user.login()
. - When the client application subsequently calls client library methods that interact with Blogger, the client library automatically attaches the token to all requests.
Note: For the JavaScript client library to make
authenticated Blogger 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 in. We'll call the
setupMyService()
function from other code later.
function logMeIn() {
scope = "http://www.blogger.com/feeds/
";
var token = google.accounts.user.login(scope);
}
function setupMyService() {
var myService =
new google.gdata.blogger.BloggerService('exampleCo-exampleApp-1');
logMeIn();
return myService;
}
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, instead, you call
google.accounts.user.login()
immediately after loading, without
waiting for user interaction, then the first thing the user sees on arrival at
your page 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, 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 BloggerService
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 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 Blogger rejects a token, your client should handle
the error condition by calling logout()
to remove the cookie
containing the current token, and then calling 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 AuthSub, including
information on token management and on checkLogin()
and
getInfo()
, see the Using
"AuthSub" Authentication with the JavaScript Client Library
document.