by Kevin Farnham
December 31, 2007
Introduction
In the first article in this series, I introduced the AOL Journals Open Blog API, describing its foundations and its capabilities. In this article, I demonstrate how to put the API to work in an actual application that gathers and displays information from a public AOL Journals blog.
Application description
You might immediately wonder why I say this application works only with public AOL Journals blogs. The reason is that, in order to work with private blogs, the application would have to include authentication, using OpenAuth. But my purpose in this article is to focus on features that are specific to the Open Blog API. In order to be able to allocate more space to demonstrating requests and API responses related to blogs, entries, and comments, the demonstration application does not perform any requests that require authentication. This also enables any reader to be able to run the application and get the same results documented in the article.
For simplicity, the application is designed to run in Internet Explorer, taking advantage of the Microsoft.XMLHTTP ActiveX object for performing the requests to the Open Blog API and retrieving the responses. When the application is first brought up, you may have to click to allow the ActiveX object to be instantiated. Once you've approved running the ActiveX object, you'll see the following:
Figure 1. Initial Open Blog API application view
When I describe the code below, you'll have a better idea of how this page is actually constructed. Without getting into the actual code, the page can be described as follows. The three buttons launch requests to the Open Blog API. The text of the requests is displayed beneath the "The Request" heading. The response received from the API is displayed beneath the "The Response" heading. Information that is parsed out of the response text is displayed beneath the "The Information" heading. The "Latest Action" and "Status" headings are for diagnostics and logging of the actions performed as each command is executed.
Application example data set
You'll notice that at start up the application already has something entered in the top text box (beneath "Enter AOL Journals User Name"). This is my screen name that I used to create an AOL Journals blog that is used as the default data set for this article. You can enter another screen name if you'd like, when you run the application, but what's documented in this article is the specific results that are produced when you use the Open Blog API to access diyincite's AOL Journals blogs.
User diyincite has only one AOL Journals blog, the Kevin Farnham's AOL Developer Network Extras blog. Here's how the top of the front blog page looks as I write this article:
Figure 2. Top of the "Kevin Farnham's AOL Developer Network Extras" blog front page
Application design
As stated above, the application is designed to use the Microsoft Microsoft.XMLHTTP ActiveX object and must be run in Internet Explorer. I take this shortcut, again, to be able to talk more about the Open Blog API, instead of addressing browser incompatibility issues. In my view, Internet Explorer is an excellent platform for demonstrating APIs.
The Microsoft.XMLHTTP ActiveX object provides the capability to use Javascript to construct request strings that can be sent to an API, and subsequently receive response strings. Again, for simplicity, while the Open Blog API returns XML responses, an XML parser is not applied in the application. Not everyone uses or understands how to use a particular XML parser. So, to keep this article's focus on the Open Blog API itself, API responses are parsed using simple Javascript string searches and substring extractions.
The application consists of an HTML section (discussed in the "Developing..." section below), plus the following Javascript functions:
- createXMLHttpRequest() - generic HTTP Request object creation function
- handleResponse() - receives and displays Open Blog API responses
- extractBlogListInfo() - extracts and displays the blog list information
- doGetBlogList() - constructs and sends the request to receive a list of the user's blogs
- doGetBlogEntries() - constructs and sends the request to receive the entries for the specified blog
- doGetComments() - locates a blog entry that has a comment
- displayComment - extracts a comment from an entry and displays it
Developing and running the application
The HTML
In Figure 1 you saw how the application looks when you first bring it up in Internet Explorer. Now let's take a look at the HTML that's behind that page.
<body> <h3>AOL Journals Open Blog API Demo Application</h3> <form id="getBlogListForm" action="javascript:doGetBlogList();"> <strong>Enter AOL Journals User Name</strong><br/> <input type="text" name="userName" id ="userName" value="diyincite"/><br/> <input type="submit" value="getBlogList"/> </form> <br/> <h3>Get List of Entries</h3> <form id="getBlogEntriesForm" action="javascript:doGetBlogEntries();"> <strong>Enter AOL Journals Blog ID</strong><br/> <input type="text" name="blogID" id ="blogID"/><br/> <input type="submit" value="getBlogEntries"/> </form> <br/> <h3>Display Comments</h3> <form id="getCommentsForm" action="javascript:doGetComments();"> <input type="submit" value="getComments"/> </form> <br/> <p> <strong>Latest Action:</strong> <div id="actionDiv">init</div> </p> <p> <strong>Status: </strong> <div id="statusDiv"></div> </p> <p> <strong>The Request</strong> <div id="reqDiv"></div> </p> <p> <strong>The Response</strong> <div id="respDiv"></div> </p> <p> <strong>The Information</strong> <div id="infoDiv"></div> </p> </body>Listing 1. The getTest.html HTML body section
If you look back at Figure 1, it's pretty easy to see the correspondances between the code and the displayed application.
The getBlogListForm form accepts an AOL Journals user name and invokes the doGetBlogList() Javascript function when the getBlogList button is clicked.
The getBlogEntriesForm form accepts an AOL Journals blog ID and invokes the doGetBlogEntries() Javascript function when the getBlogEntries button is clicked.
The getComments button invokes the doGetComments() Javascript function when it is clicked.
The Latest Action: section includes the actionDiv <div> section, where the lastest attempted action can be reported by the Javascript functions.
The Status: section includes the statusDiv <div> section, where sequential results of attempted actions are reported by the Javascript functions.
The The Request section includes the reqDiv <div> section, where the request text sent to the Open Blog API is displayed.
The The Response section includes the respDiv <div> section, where the response text received from the Open Blog API is displayed.
The The Information section includes the infoDiv <div> section, where information parsed out of the received response is formatted and displayed.
Get blog list
The getBlogList button calls Javascript function getBlogList() to retrieve a list of the blogs that have been created by the user specified in the form.
Figure 3. View of the getBlogListForm form
So, what happens when the getBlogList button is clicked? Function doGetBlogList() is invoked. Here's the code:
function doGetBlogList() {
var processDiv = document.getElementById("actionDiv");
actionDiv.innerHTML = "getBlogList";
var statusDiv = document.getElementById("statusDiv");
statusDiv.innerHTML += "doGetBlogList<br/>";
var userName = getBlogListForm.userName.value;
if (userName == "") {
alert("you didn't enter a user!!");
return;
}
var url = "http://api.blogs.aol.com/" + userName + "/service.xml";
var reqDiv = document.getElementById("reqDiv");
reqDiv.innerHTML = url;
myReq = createXMLHttpRequest();
statusDiv.innerHTML += "send request: " + url + "<br/>";
myReq.open("get", url, true);
statusDiv.innerHTML += "check Ready State Changes<br/>";
myReq.onreadystatechange = handleResponse;
myReq.send(null);
}
Listing 2. Javascript function doGetBlogList()
The <div>'s in the HTML are identified so the relevant information can be displayed as the processing occurs. The user name entered in the getBlogListForm form is extracted into variable userName (with an error message displayed if no user was entered).
Next, the request for the Open Blog API is constructed. The request in this case is straightforward. To retrieve a list of blogs owned by a user, you simply call for the service.xml file for that user. The request text is displayed in the reqDiv.
Next, function createXMLHttpRequest() is called, to create the Microsoft.XMLHTTP ActiveX object, named myReq. The open method is invoked on myReq, passing in the request URL. Function handleResponse() is then invoked, to await the receipt of the response from the Open Blog API.
The createXMLHttpRequest() and handleResponse() functions are fairly standard for Javascript/AJAX programming, so I won't spend time detailing how they work. Basically, handleResponse() is invoked each time the ready state changes, until finally the ready state identifies that the response is complete (or that an unrecoverable error has occured).
The handleResponse() code in our application displays the received response in the respDiv <div> section. Here's how the midsection of the application looks after the getBlogList button is clicked for user name diyincite:
Figure 4. Application midsection after the getBlogList button is clicked
Here we see the relatively simple request that is sent to the Open Blog API, and the response XML.
In this case, where the getBlogList button is being processed, handleResponse() invokes the extractBlogListInfo() function:
function extractBlogListInfo() {
var infoDiv = document.getElementById("infoDiv");
//alert("extractBlogListInfo");
var str = new String(myReq.responseText);
var idxHref = str.search("href");
var str1 = new String(str.substring(idxHref + 6));
var idxQuot = str1.search("'");
var theURL = new String(str1.substr(0,idxQuot));
var idxLastSlash = theURL.lastIndexOf("/");
var blogID = theURL.substr(idxLastSlash + 1);
infoDiv.innerHTML = "<p><strong>URL:</strong> " + theURL +
"<br/><strong>blogID:</strong> " + blogID + "</p>";
getBlogEntriesForm.blogID.value = blogID;
}
Listing 3. Javascript function extractBlogListInfo()
Function extractBlogListInfo() is fairly straightforward. The response text shown in Figure 4 is parsed using basic Javascript string functions, extracting the user's first blog URL and the blog ID. These are output in the infoDiv <div> section:
Figure 5. Parsed information from getBlogList button click
Get blog entries
At this point, in the particular instance we're working with, we know that user diyincite has a single AOL Journals blog, and we know its fundamental information (the URL and blogID). Now, let's apply the Open Blog API to retrieve the blog entries for the "Kevin Farnham's AOL Developer Network Extras" blog:
Figure 6. View of the getBlogEntriesForm form
The application automatically selects the user's first blog as the default entry for the form; but you can enter another blogID if you'd like. Just make sure it's a valid ID that was listed in the XML response returned by the getBlogList button click.
When the getBlogEntries button is clicked, Javascript function doGetBlogEntries() is invoked:
function doGetBlogEntries() {
var actionDiv = document.getElementById("actionDiv");
actionDiv.innerHTML = "getBlogEntries";
var statusDiv = document.getElementById("statusDiv");
statusDiv.innerHTML = "doGetBlogEntries<br/>";
var userName = getBlogListForm.userName.value;
if (userName == "") {
alert("you didn't enter a user!!");
return;
}
var blogID = getBlogEntriesForm.blogID.value;
if (blogID == "") {
alert("you didn't enter a blog ID!!");
return;
}
var url = "http://api.blogs.aol.com/_atom/collection/" + userName + "/" + blogID;
var reqDiv = document.getElementById("reqDiv");
reqDiv.innerHTML = url;
myReq = createXMLHttpRequest();
statusDiv.innerHTML += "send request: " + url + "<br/>";
myReq.open("get", url, true);
statusDiv.innerHTML += "check Ready State Changes<br/>";
myReq.onreadystatechange = handleResponse;
myReq.send(null);
}
Listing 4. Javascript function doGetBlogEntries()
This function is similar in many ways to function doGetBlogList() (see Listing 2). The primary difference is in the construction of the Open Blog API request string. In this case, the request is of form:
http://api.blogs.aol.com/_atom/collection/userName/blogID
where userName is the user name entered in the getBlogListForm form, and blogID is the blogID entered in the getBlogEntriesForm form.
Once again, the function displays the request URL text in the reqDiv <div> section. Function handleResponse() takes care of receiving the HTTP response, and displays the response XML as text in the respDiv <div> section.
Here's how the application midsection looks after user diyincite's blog with ID dev-aol-com is accessed by a click of the getBlogEntries button:
Figure 7. Application midsection after the getBlogEntries button is clicked
Clearly, the response from the "get blog entries" request is rather large. This is shown from the vertical scrolling bar in the The Response section. So, how do we extract information from this quite large XML text block?
Get comments
In this application, the objective is to locate and display a comment that was posted to one of the blog entries. This is performed when the getComments button is clicked:
Figure 8. View of the getComments button, about to be clicked
Clicking the getComments button invokes Javascript function doGetComments(). This is a rather large function, but it's not all that complex. It takes the response XML string that was returned by the getBlogEntries button click and parses it, locating the first entry that has at least one comment. Then, the function displays information about both the blog entry and the comment in the The Information <div> section. Here's how that looks after the getComments button is clicked for AOL Journals user diyincite's blog with blogID dev-aol-com:
Figure 9. The The Information section after the getComments button is clicked
We can see the results of all the hard work done by function doGetComments(). The function has located a blog entry with a comment and created a fully-formatted Web page section that displays the blog post and comment.
Conclusion
Looking back at Figure 2, you see that the Open Blog API did what it promised: it correctly identified that user diyincite owns the blog with blogID dev-aol-com (which is titled "Kevin Farnham's AOL Developer Network Extras"), and that blog has an entry titled "Open Blogs API test post" which has a comment. The application interacted with the Open Blog API to extract both the blog entry and the comment, and displayed them in an easy-to-read format in a Web page.
So, where do you go from here? In this article I used Internet Explorer as my platform for interacting with the Open Blog API. But IE is just one of a great many possible platforms through which you can develop applications that interact with AOL Journal blogs.
In addition, the application presented in this article applies read-only access to AOL Journals blogs. If you implement authentication using Open Auth, you can apply the Open Blog API to modify and add new blog elements, from any platform that can interact using standard HTTP request/response protocol.
What I'm saying is: they sky's the limit with the Open Blog API. Once again, AOL has created a standards-based interface into its proven rock-solid backend infrastructure, that can be applied by developers for any purpose they'd like.
The AOL Journals Open Blog API is the first of its kind, from what I know. And it really is a very cool, and quite powerful, API.
Resources
- getTest.zip - zip file containing the getTest.html file documented in this article
References
- http://dev.aol.com/article/2007/openblog_api - "Introducing the AOL Journals Open Blog API," by Kevin Farnham (the first article in this series)
- http://dev.aol.com/aolblogs_api - the AOL Journals Open Blog API home page
- http://dev.aol.com/openauth - AOL OpenAuth on the AOL Developer Network