Introducing the AOL Journals Open Blog API

by Kevin Farnham
November 29, 2007

Introduction

The AOL Journals Open Blog API provides a REST-style interface for retrieving, updating, creating, and deleting a user's AOL Journals blog resources. The Open Blog API is based on the Atom Publishing Protocol. The API is integrated with the RSS capability of the AOL Journals platform. To use the API, the client submits HTTP requests, and it receives responses in XML format.

A Bit of History

Blogs and RSS

When you visit a blog, it can look a lot like any other web page, or it can have a distinctively blog-like appearance. However, what separates a blog site from a standard website is that blogs automatically create a "feed." A blog "feed" is a summary of content in blog posts. Blog aggregators, such as Technorati and Feedburner, are typically "pinged" (i.e., notified) whenever the content in a blog has been updated. The aggregators visit the blog site, read the feed, and update their own catalog using the information in the feed. Blog aggregators are akin to search engines, in that they index blog posts and allow people to search for blog content of interest. The difference, however, is that blog aggregators are notified by the blog sites when new content is available, whereas search engines update their records of website content by crawling each site periodically.

Of course, none of this could work without standardization of the data structure of feeds. This is where RSS comes in. Surprisingly, the history of RSS is one of tumult. There isn't even agreement on what the letters RSS stand for: does RSS mean "Rich Site Summary" or does it mean "Really Simple Syndication?" Or perhaps "RDF Site Summary?"

The first RSS (version 0.9) was created at Netscape in 1999. This version was later both simplified and extended to become RSS version 0.91. Version 0.91 was the standard RSS version for a long time because of a fairly acrimonious debate over what RSS 1.0 should look like. The debate was not resolved, and subsequently a version 1.0 was released, followed by a version 0.92 and a related version 2.0 that was significantly incompatible with the already released version 1.0.

As you can see, we've ended up with several different RSS "standards"--which really means that we don't have a standard. The Wikipedia RSS entry provides a nice summary of the history and trials of RSS. Despite the disagreements, RSS in essence created the possibility of feeds, and hence enabled the formation of what we've come to call the "blogosphere."

Atom Syndication Format

Clearly, a divided "standard" is a problem: who wants to have to be forced to always program for multiple feed formats? Hence, RSS's infighting and resultant incompatibility issues left the door for a competitor: enter Atom.

The Atom syndication format was published as an IETF (Internet Engineering Task Force) proposed standard in RFC 4287. Atom "is designed to be a universal publishing standard for personal content and weblogs" (home page, AtomEnabled.org). You can see a description of the Atom syndication format at the Atom syndication format page on the AtomEnabled.com site. Here is the example Atom feed from that page:

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">

  <title>Example Feed</title>
  <link href="http://example.org/"/>
  <updated>2003-12-13T18:30:02Z</updated>
  <author>
    <name>John Doe</name>
  </author>
  <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>

  <entry>
    <title>Atom-Powered Robots Run Amok</title>
    <link href="http://example.org/2003/12/13/atom03"/>
    <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
    <updated>2003-12-13T18:30:02Z</updated>
    <summary>Some text.</summary>
  </entry>

</feed>

Atom Publishing Protocol

The Atom Publishing Protocol (APP) is an application-level protocol for publishing and editing web resources using HTTP and XML. A quick look at the Atom Publishing Profile structure reveals the close association of APP actions with those of the Hypertext Transfer Protocol (HTTP). The Open Blog API Reference describes the Atom Publishing Protocol (APP) as follows:

APP is a REST-based protocol which uses the HTTP methods GET, PUT, POST, and DELETE to manipulate server collection (blog), entry, and comment resources.

The Atom Publishing Protocol specification identifies the following methods for creating and editing resources:

• GET: For retrieving a representation of a known resource.
• POST: For creating resources, adding members to a collection.
• PUT: For editing member resources.
• DEL: For deleting member resources.

From this, we see the close association of the Atom Publishing Protocol with HTTP.

The Atom Publishing Protocol has been published as a proposed IETF standard in IETF RFC 5023.

AOL Journals

AOL Journals is AOL's standards-based blogging platform. The Open Blog API's actual title is "AOL Journals - Open Blog API," because the AOL Journals software has been enhanced in order to make it responsive to the requests and commands in the API. Hence, the example code in this article, and the application in the second article in this series, apply to AOL Journals blogs only (at this time).

RSS/Atom and the AOL Journals Platform

An Atom feed is automatically created for each AOL Journal. When you are viewing an AOL Journal, you'll also notice the standard blog feed symbol next to a "Get the Feed" link. If you click this link, and you have blog reading software installed on your computer, your blog software will attempt to add the blog to the list of feeds you follow.

If you choose to download the feed onto your computer, and then pull it up in a text editor, you'll see a file formatted using the standard Atom feed structure.

How the Open Blog API Fits into All of This

The AOL Journals - Open Blog API applies the other side of Atom, the Atom Publishing Protocol, with some extensions, providing access to and manipulation of AOL Journals blog resources. With the Open Blog API, you can programmatically access and manipulate the AOL Journals blogs you own. For example, you could write software that lets you access your AOL Journal blog from devices other than a standard computer. Your application could even let you post new entries using the API.

OpenBlog API Features Presentation

The Role of XML, REST, and HTTP

The Open Blog API applies a REST-style interface that is based on the Atom Publishing Protocol. Since APP is structured to resemble HTTP, experienced web developers will find the request and response client/server structure of the Open Blog API to be quite familiar. Now let's take a look at some of the details, so you can see what I mean.

Data Structure: The AOL Journals Blog Hierarchy

AOL Journals are structured in a hierarchy consisting of owners, blogs, entries, and comments; each owner (user) can own multiple blogs. Each blog has multiple entries (blog posts). Each entry/post can have multiple comments. All of these have a unique identifier. The identifiers are the means by which individual owners, blogs, entries, and comments are specified in Open Blog API requests sent to the server.

• ownerID
• blogID1
• entryID1
• blogID2
• entryID2
• entryID3
• commentID1
• commentID2
• entryID3
• commentID3
• blogID3
• ownerID2

The API provides a different set of options for each of these.

Actions

The Open Blog API is based on the Atom Publishing Protocol, with some extensions. Hence, as you'd expect, the Open Blog API supports four types of action designators: GET, PUT, DELete, and POST. Again, if you're familiar with the HTTP protocol, you'll be able to predict the actions that each of these commands perform. Review the bullets above in the "Atom Publishing Protocol" section, if you're not familiar with HTTP or APP and you'd like to refresh your memory regarding each action's purpose.

For a given blog owner, the Open Blog API allows retrieving the list of blogs (GET) and creating a new blog (POST). For an individual blog, the API allows returning a feed for the blog (GET), modifying the blog's core information (PUT), deleting the blog (DEL), and adding a new entry to the blog (POST). For an individual blog entry, the API provides the capability to retrieve the entry and its comments (GET), modify the entry (PUT), delete the entry (DEL), and create a new comment for the entry (POST). Finally, for an individual comment, the API allows deletion of the comment (DEL).

Table 1 shows which actions are available for each of the AOL Journals blog resource categories.

Resource	GET	PUT	DELete	POST
ownerID	yes	no	no	yes
blogID	yes	yes	yes	yes
entryID	yes	yes	yes	yes
commentID	no	no	yes	no

Table 1. Open Blog API actions available for each AOL Journals blog resource

While Table 1 shows which actions can be applied to each blog resource, looking at the Open Blog API in this summarized manner is a bit misleading. For example, the table shows that only the DEL action can be applied to a specific commentID. Yet, as stated in the paragraph above Table 1, comments are retrieved when GET is applied to an entry. In addition, comments can be created using the API (through a POST operation performed on an blog entry).

What you notice is that POST actions create a new child resource, not a new instance of the resource to which the POST is applied. Likewise, GET actions return a list of the child resources for the resource to which the GET is applied. With this in mind, we can create a new grid that shows what resources can be created, updated, retrieved, and deleted.

Resource	Retrieve	Update	Delete	Create
owner	no	no	no	no
blog	yes	yes	yes	yes
entry	yes	yes	yes	yes
comment	yes	no	yes	yes

Table 2. Open Blog API resource retrieval, update, deletion, and creation capabilities

Looking at the API in this manner, the structure of the API and the actions it provides look quite sensible. Nothing can be altered with respect to ownerIDs using the API. Nor is there a capability to retrieve a list of ownerIDs. Hence, the privacy of individual AOL Journals blog owners is protected.

Meanwhile, it is possible to retrieve, update, delete, and create blogs and blog entries; and comments can be retrieved, deleted, or created, but not updated.

This is, indeed, the full range of capability that we'd want a blog owner to have. The owner can do anything and everything with blogs and individual blog entries. When it comes to comments, the blog owner can view, delete, or create them, but cannot modify them. The inability to modify comments is reasonable, since most blog comments are not created by the blog owner; deletion of a comment is an option the blog owner can take, but changing a comment that was created by someone else is inappropriate.

Data Elements

Now that we know what actions are possible, it's useful to know what types of data the API provides access to. For example, what does it mean to GET an owner's blogs? What information does the API return when this request is submitted?

The Open Blog API Reference provides a complete list of data element names and details for all AOL Journals blog resources. I'll provide a quick summary here. Note that many of the elements in each category are optional.

• For blogs, the available data includes: ID, title, subtitle, last update time, author information, blocked users, and total number of entries and comments.
• For blog entries, the available data includes: ID, title, content, last update time, author, number of comments, mood, and music.
• For comments, the available data includes: ID, title, content, comment creation time, and author.

What About Security? Authentication (Using OpenAuth)

APIs are nice, but you certainly don't want someone other than yourself tampering with your blog. So how is security handled in the Open Blog API?

AOL Journal blogs are all linked to the owner's AOL/AIM screen name. To add an entry, create a blog, or do anything like that to a blog you own, using the on-site user interface, you first have to log in using your screen name.

A similar approach is used for the Open Blog API. In this case, your application "logs in" using AOL OpenAuth. OpenAuth returns a token when a successful login attempt has occurred. This token is then included in an authorization header of the form:

OpenAuth token="(token)"

where (token) is the authorization token that was returned in the OpenAuth login response.

Getting Your DevID

You also need a developer ID (DevID) to use the Open Blog API. You can get your DevID key at the AOL key registry.

Conclusion

We've covered a lot in this article. The AOL Journals - Open Blog API is indeed a powerful standards-based platform that will empower developers to create applications that allow AOL Journals users to view and manage their blogs via any number of platforms and devices that have access to the Web.

In the second part of this series, I'll demonstrate the development of an Open Blog API application, providing a first-hand glimpse into the workings of the API. Stay tuned!

References

• The AOL Journals Open Blog API home page
• Atom Publishing Protocol introduction
• Internet Engineering Task Force RFC 4287: The Atom Syndication Format
• Atom Publishing Protocol specification
• Internet Engineering Task Force RFC 5023: The Atom Publishing Protocol
• Atom Syndication Format description
• Wikipedia's RSS entry
• Internet Engineering Task Force RFC 2616: Hypertext Transfer Protocol (HTTP/1.1)
• AOL OpenAuth on the AOL Developer Network
• AOL Developer ID (DevID) FAQ
• AOL key registry and management site