Version 1.0
We started our API by supporting the "basic" use of Atom from feed readers. From there, we expanded its use as a general tool for viewing and manipulating blogs, so that you can now do most of the things that you can do from the AOL Journals UI through our AOL Journals - Open Blog API. This includes functionality such as:
- Getting all the blogs for a user
- Reading a blog, with entries
- Updating much of the blog information
- Reading, writing and updating individual blog entries
- Reading, adding and deleting comments on a blog entry
We have done so using a simple, standards-based HTTP REST interface, requiring you to just formulate HTTP requests and parse XML responses.
The Atom standard provided a framework for accomplishing all these actions, so we have stuck close to those standards. Details about Atom itself are outside the scope of this "Getting Started" document. Look at the main API document for details on that interaction.
A Note on Domains
Those of you who may be familiar with AOL already may know that our blogs service is branded as "Journals," and accordingly has a domain of journals.aol.com. You should also note below that all the API requests are made to api.blogs.aol.com rather than journals.aol.com, or even api.journals.aol.com. We decided to use this domain to represent that this is a generalized blogs interface, and that it's specifically an API interface. You should use the api.blogs.aol.com domain for all your API calls (GETs to journals.aol.com will work, but PUTs, POSTs and DELETEs will not).
DevId Key
DevId keys are used to track and control usage of AOL APIs. While they're not required for blog read requests, they are required for write requests, and recommended for all. They are available from our central AOL key registry at http://dev.aol.com/keys.
You send your DevId with requests in an X-AOL-DEVID header. If the request is not from a client (browser - e.g. via AJAX) then you also need to add a Referer header, the contents of which must be the URL of your your site (the same that you assigned to your DevID key).
Atom Feed Request
As mentioned above, we started by supporting Atom feed requests, so let's start our examples from here also. A feed request is a request to get the information about a blog and the recent entries for that blog. This is normally done by merely appending /atom.xml onto the resource you want to get a feed from. So, for example, for blog http://blogs.aol.com/bsteinback0224/counter you just do an HTTP GET of: http://api.blogs.aol.com/bsteinback0224/counter/atom.xml
By the way, you can do this from your browser; IE6 renders the XML nicely! You'll get back the following XML. Let's inspect it!
Our comments are set off in standard notation. Pay special attention to the fact that this is the actual result from a public AOL blog. Try it out! By default, this request will give you the 10 most recent entries. For brevity, we're just showing one here. Finally, we also removed some fields that we're not documenting currently. They're 'internal' - you can't modify them, so they're best ignored
<?xml version="1.0" encoding="utf-8" ?>
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:aj="http://schema.blogs.aol.com/_atom/aj#"
xml:lang="en">
/**
* The link elements below are standard Atom.
* They tell you how to do all the operations you might want to do on the blog.
* For example, the first tells you how to get the blog from your browser;
* the 2nd how to recreate this response,
* the 3rd-5th how to get more entries,
* the 6th-8th how to modify the blog
*/
<link rel="alternate" type="text/html"
href="http://beta.journals.aol.com/bsteinback0224/counter/" />
<link rel="self" type="application/atom+xml" title="Page 1 of 2"
href="http://api.beta.blogs.aol.com/bsteinback0224/counter/atom.xml" />
<link rel="previous" type="application/atom+xml"
href="http://api.beta.blogs.aol.com/bsteinback0224/counter/atom.xml?page=2&count=10" />
<link rel="first" type="application/atom+xml"
href="http://api.beta.blogs.aol.com/bsteinback0224/counter/atom.xml?page=first&count=
10" />
<link rel="last" type="application/atom+xml"
href="http://api.beta.blogs.aol.com/bsteinback0224/counter/atom.xml?page=last&count=
10" />
<link rel="edit" type="application/atom+xml" title="Edit Blog definition"
href="http://api.beta.blogs.aol.com/_atom/collection/bsteinback0224/counter" />
<link rel="http://schema.blogs.aol.com/service.post" type="application/atom+xml" title=
"Post an entry"
href="http://api.beta.blogs.aol.com/_atom/collection/bsteinback0224/counter" />
<link rel="http://schema.blogs.aol.com/userlist.readers" type="text/html" title="Readers,
format=xhtml|xoxo|json"
href="http://api.beta.blogs.aol.com/_atom/list/bsteinback0224/counter/readers" />
/* These are deprecated links, for pre-existing applications, ignore them */
<link rel="http://journals.aol.com/service.edit" type="application/atom+xml" title=" --
Link Deprecated -- "
href="http://api.beta.blogs.aol.com/_atom/collection/bsteinback0224/counter" />
<link rel="http://journals.aol.com/service.post" type="application/atom+xml" title=" --
Link Deprecated -- "
href="http://api.beta.blogs.aol.com/_atom/collection/bsteinback0224/counter" />
<link rel="http://journals.aol.com/userlist.contributors" type="text/html" title=" --
Link Deprecated -- "
href="http://api.beta.blogs.aol.com/_atom/list/bsteinback0224/counter/contributors" />
<link rel="http://journals.aol.com/userlist.readers" type="text/html" title=" -- Link
Deprecated -- "
href="http://api.beta.blogs.aol.com/_atom/list/bsteinback0224/counter/readers" />
/* This is the reference ID (Permalink) for this blog */
<id>tag:api.blogs.aol.com,2003:/bsteinback0224/counter</id>
/**
* Below is the blog title.
*/
<title type="text">
<![CDATA[counter]]>
</title>
<updated>2007-08-31T16:34:40Z</updated>
/**
* This is the owner of the blog.
*/
<author>
<name>bsteinback0224</name>
</author>
/**
* Below is the blog description.
*/
<subtitle type="text">
<![CDATA[ let's see if we can find where Archive Year breaks ]]>
</subtitle>
/**
* This is the blog identifier used in the blog URL.
*/
<aj:blogShortName>counter</aj:blogShortName>
/**
* and this tells that it's a public blog.
*/
<aj:accessType>public</aj:accessType>
/**
* Total number of entries in this blog.
*/
<aj:entryCount>20</aj:entryCount>
/**
* Total number of comments in this blog (for all entries).
*/
<aj:commentCount>4</aj:commentCount>
<aj:lastEntryCreationDate>2006-11-10T19:53:12Z</aj:lastEntryCreationDate>
<aj:journalLocale>en_US_aol</aj:journalLocale>
/**
* Below is the first entry in the blog.
*/
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:aj="http://schema.blogs.aol.com/_atom/aj#">
/**
* Similarly to the above blog links, these below tell how to do operations on this entry.
* The first tells how to get it in a browser.
*/
<link rel="alternate" type="text/html"
href="http://journals.aol.com/bsteinback0224/counter/entries/2007/02/15/now-im-
curious/1230"/>
/**
* The link below tells how to get an Atom response on just this entry, including comments
*/
<link rel="edit" type="application/atom+xml"
href="http://api.blogs.aol.com/_atom/collection/bsteinback0224/counter/entryid=1230"/>
/**
* And now the elements that describe the entry.
* First is the Permalink (permanent reference)
*/
<id>tag:journals.aol.com,2003:/bsteinback0224/counter/1230</id>
<title type="text">
<![CDATA[ Now I'm curious ]]>
</title>
<updated>2007-08-31T16:34:40Z</updated>
<published>2007-02-15T23:09:15Z</published>
<author>
<name>bsteinback0224</name>
</author>
<aj:mood>2</aj:mood>
<aj:commentCount>3</aj:commentCount>
<aj:music type="text"> <![CDATA[ Mrs. Potter's Lullaby ]]> </aj:music>
<content type="html">
<![CDATA[ Okay, let's see if this shows up on AIM Update...<br/><div class="tags"
id="tagsLocation"><br/>Tags:
<a rel="tag" target="_blank" href="http://technorati.com/tag/testing">testing</a>
</div> ]]>
</content>
</entry>
</feed>
As the above links suggest, using the page and count parameters you can get all the entries for a blog. Count is number of entries per page (default=10), and page gets you the appropriate segment. It's always by entry publish date, from the most recent entry. Note that the same scheme works for comment paging for an entry. By default only the latest 10 comments are published with an entry, but you can page thru prior comments.
However (as you can tell from the links above), that's just the start of what you can do with this API. Let's go into some examples of how you can make modifications.
Authenticating
Of course, to do any modifications on a blog, or in order to view private blogs (the blog above is public), one must be authenticated. This is accomplished using AOL OpenAuth.
Once your application has logged a user into AOL using OpenAuth, we will honor the token received from the OpenAuth login. You just need to include the token in an Authorization header (with content: OpenAuth token="(token)"), and your site DevId in an X-AOL-DEVID header. If you're not calling from a browser (i.e. Javascript) then you'll also need to add a Referer header, the contents of which must be the URL of your your site (the same that you assigned to your DevID key).
Adding an Entry
It feels a bit uncomfortable at first if you're not used to REST-style interfaces, but in order to add an entry to a blog you do a POST to the blog URL. For example, if your screenname is "memyself", and you want to add an entry to your blog: myblog, you just do a post to the following URL: http://api.blogs.aol.com/_atom/collection/memyself/myblog
The data comprising the post for the blog will be in the data sent with the POST, in XML format. So, putting it all together, let's construct a CURL (commonly available HTTP Client application) request:
curl -v --request POST --header "Content-Type: application/atom+xml;charset=UTF-8" --header 'Authentication: OpenAuth token="%2FwEAAAAABYgbMtk4J7Zwqd8WHKjNF6fgJSYe4RhTuitkNotes:
Nyip%2BEru%2FY43vaGyE2fTlxKPAEkBC%2Bf 5lhWg18CE2gaQtTVQy0rpillqtUVOOtrf1%2BLzE%2BNTc
BuFJuLssU%2B6sc0%3D"' --header "X-AOL-DEVID: eu1aEAO-mu4ToP9U" -referer "http://mymashup.com/" --data @data_file http://api.blogs.aol.com/_atom/collection/memyself/myblog
- -v is verbose, this just provides extra information about the curl request
- POST requests are used for adding new items (blogs, entries or comments)
- --header attaches the Content-Type to the request, needed for processing POST data
- the second --header contains the AOL DevId for your service.
- the referer is the URL associated with your DevId (should match the URL for your service).
- the Authorization header - needs a token returned from an AOL OpenAuth login.
- --data points to a file (in this case entry_file) containing the post data, which should look like below
This is what the new entry (entryfile) should look like. Pay special attention to the fact that the title and content fields are required for any entry; all others are optional:
<?xml version="1.0" encoding="utf-8" ?> <entry xmlns="http://www.w3.org.Atom" xmlns:aj="http://schema.blogs.aol.com/_atom/aj#"> <title type="text"">This is the Entry title</title> <content type="html">This is <b>just</b>some text for the entry</content> </entry>
The response should look like this, returning the added entry:
HTTP/1.1 201 Created
Date: Fri, 31 Aug 2007 22:17:50 GMT
Server: Apache/2.0.54 (Unix) mod_ssl/2.0.54 OpenSSL/0.9.7e mod_jk/1.2.14
Location: http://api.beta.blogs.aol.com/_atom/collection/memyself/myblog/entryid=21
<?xml version="1.0" encoding="utf-8" ?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:aj="http://schema.blogs.aol.com/_atom/aj#">
<link rel="alternate" type="text/html"
href="http://journals.aol.com/memyself/myblog/entries/2007/05/18/this-is-the-entry-
title/21"/>
<link rel="edit" type="application/atom+xml"
href="http://api.blogs.aol.com/memyself/myblog/entryid=21"/>
<link rel="http://schema.blogs.aol.com/comments" type="application/atom+xml" title="
Comments feed for this entry"
href="http://api.blogs.aol.com/memyself/myblog/entries/2007/05/18/this-is-the-
entry-title/21/atom.xml"/>
<id>tag:journals.aol.com,2003:/memyself/myblog/21</id>
<title type="text">
<![CDATA[This is the Entry title]]></title>
<updated>2007-05-18T22:18:00Z</updated>
<published>2007-05-18T22:18:00Z</published>
<author>
<name>memyself</name>
</author>
<aj:entrySource>AtomAPI</aj:entrySource>
<aj:mood>0</aj:mood>
<aj:commentCount>0</aj:commentCount>
<content type="html">
<![CDATA[This is <b>just</b>some text for the entry]]></content>
</entry>
Modifying entries is done in a similar fashion. You just do a PUT instead of a POST, and the URL now includes the entryID, e.g. a POST to modify the entry added above would be sent to: http://api.blogs.test.aol.com/_atom/collection/memyself/myblog/entryid=11 Also, you only need to put the elements you want to change into the file, e.g. to just change the mood on the above entry you'd include a body of:
<?xml version="1.0" encoding="utf-8" ?> <entry xmlns="http://www.w3.org.Atom" xmlns:aj="http://schema.blogs.aol.com/_atom/aj#"> <aj:mood>3</aj:mood> </entry>
A Note on Entry URLs
When we give out an URL to a blog entry, we usually include the entry date and title for readability. These are not necessary when accessing the entry. So, for instance, for the entry above:
http://api.blogs.aol.com/journalseditor/bsteinback0224/counter/entries/2007/02/15/
now-im-curious/1230
When reading or updating the entry, the URL is just:
http://api.blogs.aol.com/bsteinback0224/counter/entries/entryId=1230"/>
Similarly, when reading the comments for the entry, you can just use:
http://api.blogs.aol.com/journalseditor/magicsmoke/entries/2199/atom.xml(though you can use the full 'readable' URL here if you wish)
That should be able to get you going. Now dive into the full API description to see all the other stuff you can do, and have fun. Please share your experiences, successes and issues with the community through our forums.