Version 1.0

Overview
1. Authentication
2. Application ID
Blogs API Reference
Namespace and Custom Elements
1. Feed Extensions
2. Entry Extensions
Element Reference
Link Relations
Access Control List Handling API
Appendix A - Atom Standards Deviations

Overview

This document describes the AOL Journals - Open Blog API, which allow for creation, deletion, retrieval, and updates to blogs, entries, and comments. The API is an implementation of the Atom Publishing Protocol with custom extensions. It is integrated with the RSS/Atom feeds produced by AOL Journals.

This reference assumes familiarity with the basics of the Atom Syndication Format and the Atom Publishing Protocol (APP). The following resources may be useful:

The Atom Standard (Wikipedia) - General definition and overview.
Getting to Know the Atom Publishing Protocol - IBM Developer Works article by James Snell.
Atomenabled.org - Collection of Atom-related resources.

General notes:

The format follows RFC 4287 Atom Syndication Format 1.0 with some optional extensions documented below.
The publishing protocol fairly closely follows the newly released APP RFC. There are some deviations in our Blog API, as noted in Appendix A. Many of the differences have to do with the fact that the draft has still been in flux even up until fairly recently. We will attempt to become compliant with the final RFC in the near future, now that it has been finalized.
It is REST based; operations are performed on resources using HTTP methods GET, POST, PUT and DELETE. The primary resources are blogs, entries, and comments. Blogs are represented by Atom collections. Both entries and comments are represented by atom:entries.
A read only syndication feed is published automatically for every blog at blogurl/atom.xml. This document primarily discusses the editable collection which is at a separate URL but which exposes the same resources. In some cases the editable collection may contain more or less information or be ordered differently than the syndication feed.
All requests and responses are UTF-8 encoded. Clients should encode all request data in UTF-8 and should expect results to be in UTF-8.

Dev ID

A devId identifies the application or web site making a request on behalf of a user. We recommend that clients pass a devId with each request. POST, PUT or DELETE requests without a devId will be rejected. A devId can be obtained from http://dev.aol.com/keys. To pass the devId, use the custom header X-AOL-DEVID.

In addition, whenever the request is being made from a server (as opposed to an AJAX request from the client), a referer header is required, matching the URL issued with the DevId.

Example:

GET /_atom/collection/exampleuser/myblog HTTP/1.1

Host: api.blogs.aol.com

 X-AOL-DEVID: co1DRMvigZJXvWk

 REFERER: http://mymashup.com

A request with a bad or blocked DevId will receive the response: 444 Dev ID key access denied (AKES deny)

Authentication

All modify and some read operations require authentication; other reads return different representations depending on the currently authenticated user. Blogs accepts AOL's OpenAuth authentication, a secure and simple method for third parties to log users into AOL applications.

Blogs accepts OpenAuth tokens via the standard Authorization: header:

Authorization:
OpenAuth token="%2FwEAAAA....%3D"

The token is obtained by presenting your user with an AOL OpenAuth login. Details on how this is accomplished are available in our OpenAuth API area.
All Authorization requests must be accompanied with a DevId in an X-AOL-DEVID header, and a REFERER header if sent from a server -see DevId Section above for more information.
On success, the normal Atom response is returned. If authorization fails, a 401 response is returned with a WWW-Authenticate: header providing additional details.

WWW-Authenticate: OpenAuth realm="AOLBlogs", status="status", msg="message", url="url"

Example Atom request using OpenAuth token (note: Requires valid devId/referer combination, see above):


curl -k -v -sS --include --location-trusted --request POST 
 --url 'http://api.blogs.aol.com/_atom/collection/exampleuser' 
 --data @/tmp/newblog --header 'Content-Type: application/atom+xml; charset=utf-8' 
 --header 'X-AOL-DEVID:co1DRMvigZJXvWk' 
 --header 'referer http://mashup.com' 
 --header 'Authorization: OpenAuth token="%2FwEAAAAABYgbMtk4J7Zwqd8WHKjNF6fgJSYe4
RhTuitkNyip%2BEru%2FY43vaGyE2fTlxKPAEkBC%2Bf5lhWg18CE2gaQtTVQy0rpillqtUVOOtrf1
%2BLzE%2BNTcBuFJuLssU%2B6sc0%3D"'

Blogs API Reference

The Blogs API is based on the Atom Publishing Protocol (APP) with various extensions. 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. In AOL Blogs, standard protocol URLs start with the /_atom/ prefix, and subsequent parts of the path categorize the type of resource being manipulated. There are also alternate URLs available for some GETs. As an overview, the resources and their URI templates are given below. In general, an ownerId is a screen name and a blogId is the name of a blog. Blog names are unique within a given owner's namespace.

The following explains the connection between a set of blogs belonging to a person, and the actions that can be taken:

Most of of these are discoverable via link relationships starting from the APP service document. The remainder of this section describes the resources available. AOL Blogs defines an APP service document for each user. and how to create, edit, delete, and query for them using the API.

Service Documents and the Blog Workspace

This service document contains a set of collections, one for each blog owned by the user. This can be retrieved by composing a URI: http://api.blogs.aol.com/{ownerId}/service.xml. The workspace element contains a atom:collection element for each blog belonging to that user. (AOL Blogs does not yet support binary media Atom collections but may do so in the future.) The atom:collection element in turn points at the collection of entries for that blog; retrieving the collection returns recent entries, and POSTing to it creates new entries.

Example Request:


GET /exampleuser/service.xml HTTP/1.1
Host: api.blogs.aol.com
Authorization: OpenAuth token="..."
X-AOL-DEVID: co1DRMvigZJXvWk

Response:

HTTP/1.1 200 OK
Content-Type: application/atomserv+xml;charset=UTF-8
<?xml version="1.0" encoding="utf-8" ?>
<service xmlns='http://purl.org/atom/app#'
         xmlns:atom='http://www.w3.org/2005/Atom'>
<workspace>
<atom:title><![CDATA[(exampleuser blogs]]></atom:title>
<collection href='http://api.blogs.aol.com/_atom/collection/exampleuser/AtomBlog-01'>
<atom:title><![CDATA[My Blog]]></atom:title>
<accept>entry</accept>
</collection>
<collection href='http://api.dev.blogs.aol.com/_atom/collection/exampleuser/a-second-blog'>
<atom:title><![CDATA[A Second Blog]]></atom:title>
<accept>entry</accept>
</collection>
</workspace>
</service>

AOL Blogs also defines individual Service Documents corresponding to each blog, at the URI http://api.blogs.aol.com/{ownerId}/{collectionName}/service.xml. This returns a filtered version of the user's Service Document, containing only the workspace for that one blog.

Note that the respresentation of the Service Document may change depending on who is accessing the document; the owner gets a full representation if authenticated, while nonowners see only collections to which they have read access. Thus, private blogs may not show up if doing a general, unauthenticated service discovery.

Blog Collection Resources

Blogs are represented by Atom collections. While APP does not provide for creation or editing of collections, AOL Blogs provides for these via extensions.

Creating a Blog

Create a new blog by POSTing an appropriate atom:feed document to the endpoint below. In general any feed elements except <entry> are allowed on initial creation, though some may be overridden or ignored. In general fields which cannot be used are ignored. Upon success, a 201 Created response provides the newly created collection document and its URL via the Location: header.

POST /_atom/collection/{userId}

Endpoint URI: The format of the endpoint is http://api.blogs.aol.com/_atom/collection/{userId}. Authentication and DevId are required.

Result Codes:

201 Created (+ Location heading indicating URI of newly created blog)
400 Invalid request ( xml syntax error, invalid element or element value)
401 Unauthorized - authentication required
403 Forbidden
500 Internal server error

Example Request:

POST /_atom/collection/exampleuser HTTP/1.1
Host: api.blogs.aol.com
Authorization: OpenAuth token="..."
X-AOL-DEVID: co1DRMvigZJXvWk
<?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">
<title type="text">Atom Blog</title>
<subtitle type="text">Testing Atom API for Blog</subtitle>
<aj:blogShortName>AtomBlog-01</aj:blogShortName>
<aj:accessType>public</aj:accessType>
<author>
<name>exampleuser</name>
<email>exampleuser@aol.com</email>
</author>
</feed>

Response:

HTTP/1.1 201 Created

Location: http://api.blogs.aol.com/_atom/collection/exampleuser/AtomBlog-01

Content-Type: application/atom+xml;charset=UTF-8

<?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">
<link rel="alternate" type="text/html"
      href="http://journals.aol.com/exampleuser/AtomBlog-01/"/>
<link rel="self" type="application/atom+xml"
      href="http://api.blogs.aol.com/exampleuser/AtomBlog-01/atom.xml"/>
<link rel="edit" type="application/atom+xml" title="Edit Blog definition"
      href="http://api.blogs.aol.com/_atom/collection/exampleuser/AtomBlog-01"/>
<link rel="http://schema.blogs.aol.com/service.post" type="application/atom+xml"
      title="Post an entry"
      href="http://api.blogs.aol.com/_atom/collection/exampleuser/AtomBlog-01"/>
<link rel="http://schema.blogs.aol.com/userlist.contributors" type="text/html" 
      title="Contributors, format=xhtml|xoxo|json" 
      href="http://api.beta.blogs.aol.com/_atom/list/exampleuser/AtomBlog-01/
		contributors" />
<id>tag:journals.aol.com,2003:/exampleuser/AtomBlog-01</id>
<title type="text"><![CDATA[Atom Blog]]></title>
<aj:blogType>0</aj:blogType>
<updated>2005-12-03T03:20:09Z</updated>
<author>
<name>exampleuser</name>
<email>exampleuser@aol.com</email>
</author>
<subtitle type="text"><![CDATA[Testing Atom API for Blog]]></subtitle>
<aj:blogShortName>AtomBlog-01</aj:blogShortName>
<aj:accessType>public</aj:accessType>
<aj:postAccessType>owner</aj:postAccessType>
<aj:emailEnabled>false</aj:emailEnabled>
<aj:emailAddressID></aj:emailAddressID>
<aj:dailyEmailEntryCount>0</aj:dailyEmailEntryCount>
<aj:entryCount>0</aj:entryCount>
<aj:commentCount>0</aj:commentCount>
<aj:lastEntryCreationDate>2005-12-03T03:20:09Z</aj:lastEntryCreationDate>
<aj:journalLocale>en_US_aol</aj:journalLocale>
</aj:blogCustomHeader>
</feed>

Notes:

If certain elements are not provided, the server provides defaults. Some elements are required and requests will fail unless they are given. See the Feed Element Reference below for a full list of blog elements.

Element	Notes
aj:blogShortName	Required; must be nonempty and URL-safe. Note that this may go away in favor of the "slug" header in the future.
title	Required; must be nonempty.
subtitle	Required; must be nonempty.
aj:accessType	Defaults to "public" if not provided.
aj:journalLocale	Not required; if not provided, is derived from the server host name if possible, otherwise defaults to en_US_aol
author name author email	Not required; derived from the authentication info if not provided. Client values will be overridden by server if they conflict with authentication information

Editing Blog Metadata

Change a blog's metadata by PUTting an atom:feed document containing the new metadata (without entries) to the collection URI:

PUT /_atom/collection/{userId}/{collectionName}

Endpoint URI: The collection URI is returned in Location: header on creation, and discoverable via the link@rel="edit" href in the feed document or via the APP service document. Requires authentication.

Result Codes:
200 OK (+ Location if blogShortName was changed)
400 Invalid request ( xml syntax error, invalid element or element value, missing or bad DevId)
401 Unauthorized - authentication required
403 Forbidden
404 Blog Not found
500 Internal server error

Notes:

If the blogShortName is changed, the 200 OK response will include a Location header with the new collection URI. The old URI will still be active and will return permanent redirects to the new URI. As with the creation case, entry elements are ignored; this endpoint only supports editing the metadata about a collection, not the entries themselves.

Deleting a Blog

DELETE /_atom/collection/{userId}/{collectionName}

Endpoint URI: See above. Requires authentication.

Result Codes:
200 OK
400 Invalid request (missing or bad DevId). 401 Unauthorized - authentication required
403 Forbidden
404 Blog Not Found
500 Internal server error

Blog Entry Resources

Both blog entries and blog comments are represented as atom:entries. This section describes how to post, edit, and delete blog entries; the operations for comments are nearly identical.

Posting a Blog Entry

POST CollectionURI

Endpoint URI: The CollectionURI is found in the Atom Service Document's <collection> element. Alternatively, as an extension, it is also available via the <link> element with rel="service.post" in the feed or collection documents.

Authentication Required: Yes ( see Authentication)

Result Codes:
201 Created (+ Location URL header)
400 Invalid request ( xml syntax error, invalid element orelement value)
401 Unauthorized - authentication required
403 Forbidden
500 Internal server error

Example Request:

POST /_atom/collection/exampleuser/AtomBlog-01 HTTP/1.1
Host: api.blogs.aol.com

X-AOL-DEVID: co1DRMvigZJXvWk

referer: http://mashup.com

<?xml version="1.0" encoding="utf-8" ?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:aj="http://schema.blogs.aol.com/
_atom/aj#">
<title type="text">Atom entry #1</title>
<content type="html"><br> This is entry body </content>
<aj:mood>3</aj:mood>
</entry>

Response:

HTTP/1.1 201 Created

Location: http://api.blogs.aol.com/_atom/collection/exampleuser/AtomBlog-01/entryid=1
Content-Type: application/atom+xml;charset=UTF-8

<?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/exampleuser/AtomBlog-01/entries/1"/>
<link rel="edit" type="application/atom+xml"
      href="http://api.blogs.aol.com/_atom/collection/exampleuser/AtomBlog-01/
entryid=1" />
<link rel="http://schema.blogs.aol.com/comments"
      type="application/atom+xml" title="Comments feed for this entry"
      href="http://api.blogs.aol.com/exampleuser/AtomBlog-01/entryid=1/atom.xml" />
<id>tag:journals.aol.com,2003:/exampleuser/AtomBlog-01/1</id>
<title type="text"><![CDATA[Atom entry #1]]></title>
<updated>2005-12-05T05:34:00Z</updated>
<published>2005-12-05T05:34:00Z</published>
<author>
<name>exampleuser</name>
</author>
<aj:entrySource>AtomAPI</aj:entrySource>
<aj:mood>3</aj:mood>
<aj:commentCount>0</aj:commentCount>
<content type="html"><![CDATA[This isentry body]]></content>
</entry>

Notes:

Either <title> or <content> must be provided. <summary> is accepted but ignored.
Within an entry, the <link> element with rel="http://schema.blogs.aol.com/comments" points at the Atom collection of comments for that entry. Navigating to this document, then using the rel="service.post" link, allows posting comments for a specific entry.

Edit an Entry

PUT EditURI
<entry>..</entry>

Endpoint URI: The EditURI is found in the atom:entry's rel="edit" link. Also, it is the value for Location: response header when the entry is created.

Authentication Required: Yes ( see Authentication)

Result Codes:
200 OK
400 Invalid request ( xml syntax error, invalid element or element value)
401 Unauthorized - authentication required
403 Forbidden
404 Entry Not found
500 Internal server error

Example Request:

Change mood from Worried (3) to Happy (1).

PUT /_atom/collection/exampleuser/AtomBlog-01/entryid=1 HTTP/1.1
Host: api.blogs.aol.com
Authorization: OpenAuth token="..."
X-AOL-DEVID: co1DRMvigZJXvWk
<?xml version="1.0" encoding="utf-8" ?>
<entry xmlns="http://www.w3.org/2005/Atom"  xmlns:aj="http://schema.blogs.aol.com/
_atom/aj#">
<aj:mood>1</aj:mood>
</entry>

Response:

HTTP/1.1 200 OK
Content-Type: application/atom+xml;charset=UTF-8

<?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/exampleuser/AtomBlog-01/entries/1"/>
<link rel="edit" type="application/atom+xml"
      href="http://api.blogs.aol.com/_atom/collection/exampleuser/AtomBlog-01/
entryid=1"/>
<link rel="http://schema.blogs.aol.com/comments" type="application/atom+xml" 
      title="Comments feed for this entry"
      href="http://api.blogs.aol.com/exampleuser/AtomBlog-01/entryid=1/atom.xml"/>
<id>tag:journals.aol.com,2003:/exampleuser/AtomBlog-01/1</id>
<title type="text"><![CDATA[Atom entry #1]]></title>
<updated>2005-12-05T05:44:00Z</updated>
<published>2005-12-05T05:34:00Z</published>
<author>
<name>exampleuser</name>
</author>
<aj:entrySource>Email</aj:entrySource>
<aj:mood>1</aj:mood>
<aj:commentCount>0</aj:commentCount>
<content type="html"><![CDATA[ This is entry body<br> ]]>
</content>
</entry>

Notes:

As an extension, it is not required to repeat elements that remain the same. Only those entry elements that we want to change need to be specified. However, for compatibility with other Atom implementations clients should supply all known fields.
There is currently no concurrency control for multiple editors of a post. The latest writer 'wins' if there are race conditions. In the future we plan to implement ETag-based If-Match: headers to allow clients to ensure that they do not overwrite another person's changes.

Deleting an Entry

DELETE EditURI

URI auto-discovery: See above.

Authentication Required: Yes ( see Authentication)

Result Codes:
200 OK
400 Invalid request (xml syntax error, invalid element or element value)
401 Unauthorized - authentication required
403 Forbidden
404 Entry Not found
500 Internal server error

Example Request:

DELETE /_atom/collection/exampleuser/AtomBlog-01/entryid=1 HTTP/1.1
Host: api.blogs.aol.com
X-AOL-DEVID: co1DRMvigZJXvWk

Response:

HTTP/1.1 200 OK
Content-Type: application/atom+xml;charset=UTF-8

Notes:

Retrieve an Entry

Returns the all of the elements of a blog entry, along with the most recent comments for that entry.

GET EditURI

URI auto-discovery: See above.

Authentication Required: Yes for private blogs (see Authentication).

Result Codes:
200 OK
401 Unauthorized - authentication required
403 Forbidden
404 Entry Not Found
500 Internal server error

Example Request:

GET /_atom/collection/exampleuser/AtomBlog-01/entryid=1 HTTP/1.1
Host: api.blogs.aol.com
X-AOL-DEVID: co1DRMvigZJXvWk

Response:

HTTP/1.1 200 OK
Content-Type: application/atom+xml;charset=UTF-8

<?xml version="1.0" encoding="utf-8" ?>
<feed 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/exampleuser/AtomBlog-01/entries/1"/>
<link rel="http://self" type="application/atom+xml"
      href="http://api.blogs.aol.com/exampleuser/AtomBlog-01/1/atom.xml"/>
<link rel="http://schema.blogs.aol.com/service.post" type="application/atom+xml"
      title="Post a comment" 
      href="http://api.blogs.aol.com/_atom/collection/exampleuser/AtomBlog-01/
entryid=1"/>
<link rel="http://schema.blogs.aol.com/blog" type="application/atom+xml"
      title="Blog back link" href="http://api.blogs.aol.com/exampleuser/AtomBlog-01/
atom.xml" />
<id>tag:journals.aol.com,2003:/exampleuser/AtomBlog-01/1</id>
<title type="text"><![CDATA[Atom entry #1]]></title>
<updated>2005-12-05T05:44:00Z</updated>
<published>2005-12-05T05:34:00Z</published>
<author>
<name>exampleuser</name>
</author>
<aj:entrySource>Email</aj:entrySource>
<aj:mood>1</aj:mood>
<aj:commentCount>0</aj:commentCount>

<content type="html"><![CDATA[ This is entry body]]></content>


/* below is a comment for this entry */
<entry xmlns="http://www.w3.org/2005/Atom" 
       xmlns:aj="http://schema.blogs.aol.com/_atom/aj#">

<link rel="edit" type="application/atom+xml" 
      href="http://api.blogs.aol.com/_atom/collection/exampleuser/AtomBlog-01/
entryid=1/commentid=34" />

<id>tag:journals.aol.com,2003:/exampleuser/AtomBlog-01/1/comments/34</id>

<title type="text"><![CDATA[Comment by anotherperson}}></title>

<updated>2007-06-20T22:09:36Z<updated>

<published>2007-06-20T22:09:36Z<published>

<author>
<name>anotherperson</name>
</author>

<content type="html"><![CDATA[Just adding a comment to view in Atom]]></content<

</entry>
</feed>

Notes:

/atom.xml form of request returns the same response as _atom/collection. It is merely provided for convenience.
Recent comments for this entry are returned with the entry (see example above). The default is to return the 10 most recent comments. The comments for an entry can be paged thru just like entries are above.

Comment Handling API

The comments API is similar to the entries API, with the following differences.

There is no Service Document for comments; instead, clients must follow the rel="http://schema.blogs.aol.com/comments" link within an entry to get to the Atom collection of comments for that entry.
Comments cannot be retrieved individually. Comments for an entry are returned with that entry (see above).
Comment editing is not currently supported, only posting and deletion.

Deleting a Comment

See discussion above under Deleting an Entry.

Retrieve a Comment

See discussion above under Retrieving an Entry.

Namespace and Custom Elements

Blogs extends the Atom format by adding custom elements and custom link relations. For extension elements Blogs uses the the namespace xmlns:aj="http://schema.blogs.aol.com/_atom/aj#". All extension link relations start with the URI path "http://schema.blogs.aol.com/".

The API defines the following custom elements, which are present in both feeds/collections and in some cases on entries. Most of these elements are editable and can be specified via POST or PUT; a few are read-only or generated by the server.

Feed Extensions

These elements are children of the <feed> element in Atom documents served by Blogs, and are accepted on POST or PUT except where noted below.

aj:blogShortName. The name used as the 'slug' in the blog's URI.
aj:accessType. Access control for reading the blog's contents.
- "Public" - Readable by anyone, including anonymous users.
- "Private" - Readable by users on a selected access control list.
aj:blockList. A case insensitive string of comma separated AOL screennames who are blocked from commenting on the blog.
aj:emailEnabled. Whether the blog allows posting entries via email: "true" or "false".
aj:emailAddressID. The local part of a blog's email address (visible only to owner of collection).
aj:entryCount (read only, server maintained). Total number of entries in the complete feed.
aj:commentCount (read only, server maintained). Total number of comments in the feed across all entries.
aj:lastEntryCreationDate (read only, server maintained). Time stamp of the creation of the most recent entry.
aj:journalLocale Locale string in the format LL_CC_BBB, where LL = two letter ISO language code, CC = two letter ISO country code and BBB is a custom three letter brand code (currently aol or aim). Example: en_US_aol.

Entry Extensions

These elements are children of the <entry> element in Atom documents, and are accepted on POST or PUT except where noted below.

aj:commentCount (read only, server maintained). Total number of comments for this entry.
aj::mood An integer encoding a localizable mood. The current en-us mood values are:
- 0: none
- 1: Happy,
- 2: Mischievous,
- 3: Worried,
- 4: Silly,
- 5: Surprised,
- 6: Flirtatious,
- 7: Angry,
- 8: Ecstatic,
- 9: Frustrated,
- 10: Loopy,
- 11: Embarrassed,
- 12: Hopeful,
- 13: Anxious,
- 14: Sad,
- 15: Quiet,
- 16: Chilling
aj:music (editable) A free form string indicating what the poster is listening to at the time of the posting.

Element Reference

This section details the Atom elements and how they map to AOL Blogs data. In most cases the mapping is straightforward.

Feed (Blog) Elements

Atom Element	Data Type	Size and Range	Description	Example
id	text	<= 200 ASCII bytes	Permanent identifier for the blog.	"tag:journals.aol.com,2003:/exampleuser/AtomBlog"
title	text	<= 100 Unicode characters	The blog name (long name)	"My Fun Weblog"
subtitle	text	<= 500 Unicode characters	The blog description.	"Friday afternoon, happy hour"
published	timestamp	See http://www.w3.org/TR/NOTE-datetime	When blog was first created.	2003-12-15T14:43:07Z
updated	timestamp	See http://www.w3.org/TR/NOTE-datetime	When blog was last modified.	2003-12-15T14:43:07Z
author:name	text	<= 64 ASCII	Blog Owner's lower case compressed screen name	exampleuser
aj:blogShortName	text	<= 32 ASCII	Blog short Name	AtomBlog
author:uri	URI		OpenID URI of owner of blog; points to Blogs owner page.	http://blogs.aol.com/exampleuser
author:email	text	user@domain	Email address of owner; visible only to owner.	exampleuser@aol.com
aj:accessType	String, Case insensitive	{"Public", "Private"}	access type	Public
aj:blockList	String, Case insensitive list of SNs	<50 SNs	Users blocked from posting comments	billg,bsteinback0224
aj:entryCount	unsigned int	<= 2^32-1	number of entries	0
aj:commentCount	unsigned int	<= 2^32-1	total number of comments for all entries	0
aj:lastEntryCreationDate	timestamp	See http://www.w3.org/TR/NOTE-datetime	When the last etnry was created.	2003-12-15T14:43:07Z

Note: The elements blogType, postAccessType, recentCommentCount and blogCustomHeader are internal to Journals functionality and not of interest to outside developers.

Entry Elements (Blog entries)

Atom Tag	ContentType	Size/Range	Description	Example
id	text/plain	<= 117 + DomainMax ASCII (DomainMax is currently 18).	The external entry key.	"tag:journals.aol.com,2003/exampleuser/AtomBlog/1"
title	text/plain	<= 100 Unicode	The entry subject	"My first Post. "
content	html	<=25000 Unicode	Entry content	"What should I say about this service is: ....."
published	timestamp	See http://www.w3.org/TR/NOTE-datetime	When Entry was first created.	2003-12-15T14:43:07Z
updated	timestamp	See http://www.w3.org/TR/NOTE-datetime	When Entry was last modified.	2003-12-15T14:43:07Z
author:name	text/plain	64 ASCII	Author's lower case compressed screen name	exampleuser
aj:commentCount	unsigned int	<= 2^32-1	number of comment in an entry	0
aj::mood	unsigned int	Currently there are only 16 moods	Entry author's mood. It could be different across locales.	0
aj:music	text/plain	<= 100 unicode	music of your entry	nothing I can hear.

Note: The elements entrySource and ygpAlbumURL are internal to Journals functionality and not of interest to outside developers.

Entry Elements (Blog Comments)

Atom Tag	ContentType	Size/Range	Description	Example
id	text	<= 128 + DomainMax ASCII (DomainMax is currently 18)	The external comment key.	"tag:journals.aol.com,2003:/exampleuser/AtomBlog/1/1"
title	text	n/a	Title created by the Atom API	Comment by gkozy0034
content	text	<=2000 Unicode	Comment content	"Text"
published	timestamp	See http://www.w3.org/TR/NOTE-datetime	When Entry was first created.	2003-12-15T14:43:07Z
updated	timestamp	See http://www.w3.org/TR/NOTE-datetime	Because editing of comment sis not supported, it is always the dateCreated	2003-12-15T14:43:07Z
author:name	text/plain	64 ASCII	Author's low case compressed screen name	exampleuser

Link Relations

RFC 4287 defines a limited set of standard link tag "rel" attribute values and requires non-standard links to be either registered with IANA or to be in the form of an URL. The Blogs Atom API adds some custom links and uses the prefix http://schema.blogs.aol.com. The following table shows all links used by the API, their origin and meaning.

Link Relation	Defined by	Semantics
self	RFC 4287	The URL of the feed itself
alternate	RFC 4287	Corresponding HTML web page for the resource (or other alternative representations)
previous	IANA Registered Link	Previous page in multipaged feed
next	IANA Registered Link	Next page in multipaged feed
first	IANA Registered Link	First page in multipaged feed
last	IANA Registered Link	Last page in multipaged feed
http://schema.blogs.aol.com/service.post	Blogs Atom API	Link to post a new resource (blog, entry, comment)
edit	APP	Link to edit an entry or comment
http://schema.blogs.aol.com/service.edit	Blogs Atom API	Link to edit a resource (blog, entry, comment)
http://schema.blogs.aol.com/comments	Blogs Atom API	Comments feed for a blogs entry
http://schema.blogs.aol.com/journal	Blogs Atom API	Back link from a comments feed to the corresponding entry
http://schema.blogs.aol.com/userlist.contributors	Blogs Atom API	Link to ACL of users allowed to post entries to collection
http://schema.blogs.aol.com/userlist.contributors	Blogs Atom API	Link to ACL of users allowed to read and comment on blog

Access Control List Handling API

Each private blog (see aj:accessType) can have an access list of people allowed to read the blog (readers).

The reader list is readable and writable. The URI for reader access lists is found in the corresponding collection document as the http://schema.blogs.aol.com/userlist.readers link.

Note that only GET and PUT are supported. The access list is always presumed to exist, and is empty if no one aside from the owner has access.

There are three formats supported via a URL parameter "format": xhtml, xoxo, or json. The default is xhtml, which produces a full xhtml page with an embedded xoxo list of hCards listing the members. The xoxo format produces an AHAH XHTML fragment xoxo suitable for transclusion into a DOM. And the json format produces a standard json data structure, for example:

{status: 200, list: ["joeblow"]}

Here is an example: myblog is private blog that has readers. Making the following Curl request:

curl -v --request GET 
 --header 'Authorization: OpenAuth token="..."' 
 --header "X-AOL-DEVID: co1DRMvigZJXvWk" -referer http://mymashup.html
 --url http://api.blogs.aol.com/_atom/list/memyself/myblog/readers

You'll get back something like this:


<ol id='readers' class='xoxo'>
<li class='vcard'><a class='fn url' href='aim:goim?screenname=reader1'>reader1</a></li>
<li class='vcard'><a class='fn url' href='aim:goim?screenname=reader2'>reader2</a></li>
</ol>

where reader1 & reader2 are the current readers of the blog. Or if you prefer to parse JSON, you can make the request:


curl -v --request GET 
 --header "X-AOL-DEVID: co1DRMvigZJXvWk" -referer http://mymashup.html 
 --header 'Authentication: OpenAuth token="..."'
 --url http://api.blogs.aol.com/_atom/list/memyself/myblog/readers?format=JSON

and get back:


{status: 200, list: ['reader1', 'reader2']}

To change the list, create a list of users you want to overwrite with, in the desired format, e.g.:


{list: ['reader2', 'another1']}

(in say a file named upate.json) and then make the following call:


curl -v --request PUT  --header "Content-Type: application/atom+xml;charset=UTF-8"
     --header "X-AOL-DEVID: co1DRMvigZJXvWk" -referer http://mymashup.com 
     --header 'Authentication: OpenAuth token="..."'
     --data update.json  http://api.blogs.aol.com/_atom/list/memyself/myblog/readers

This should succeed in replacing the reader list with the names: reader2 & another1 (the default format for PUTs is JSON).

Appendix A - Atom Standards Deviations

We should follow the Atom Syndication Format RFC 4287 completely. As mentioned above, although we mostly match the Atom Publishing Protocol RFC (http://tools.ietf.org/html/rfc5023), there are differences as noted here:

APP features not implemented in Atom API

Media Resources and Media Link Entries are not supported. Pictures, movies, etc. can not be uploaded over Atom API. Only Atom resources (Content-Type: application/atom+xml; charset=utf-8) are accepted.
The Slug: request header, a hint for naming a new resource, is not recognized.
The service.xml doc does not include categories. Neither are category docs are supported.
E-Tag and modify requests. If-None-Match header is not processed for modify requests

Atom API differences from APP

With APP, all resources are created by POSTing an atom:entry. With Atom API, a new blog is created by posting atom:feed. atom:entry is used for posting blog entries and entry comments.
Feed Pagination (APP Collection Partial Lists) Atom API provides all standard link rels specified with the APP (previous, next, first, last). Also, just like in APP, the very first page/feed contains the most recently entries. However, the semantics of previous and next link rel is reversed. With APP, one moves to the next page by following the next link. With Atom API previous link is used (means "get previous entries").
The Atom API service document, service.xml, provides limited discovery capabilities. Only existing blog collections are discoverable and advertised to accept atom entries, i.e. that an atom:entry can be posted to a blog. But there is no discoverable information (service doc workspace collection) on how to create a new blog. Instead, Atom API has a custom approach. The API requires that atom:feed is posted to user collection /_atom/collections/.
A similar approach is applied for comments. There is no service.xml workspace collection for comments. The API is using a custom link per atom:entry with rel http://schema.blogs.aol.com/comments to point to the entry's comments' feed. The comments' feed itself has a custom rel link http://schema.blogs.aol.com/service.post which is to be used to post a comment for the entry

More About Open Blogs

Topic Centers

Blogs & Forums

AOL Journals - Open Blog API Reference

Contents

Overview

Dev ID

Authentication

Blogs API Reference

Service Documents and the Blog Workspace

Blog Collection Resources

Creating a Blog

Editing Blog Metadata

Deleting a Blog

Blog Entry Resources

Posting a Blog Entry

Edit an Entry

Deleting an Entry

Retrieve an Entry

Comment Handling API

Post a Comment

Deleting a Comment

Retrieve a Comment

Namespace and Custom Elements

Feed Extensions

Entry Extensions

Element Reference

Feed (Blog) Elements

Entry Elements (Blog entries)

Entry Elements (Blog Comments)

Link Relations

Access Control List Handling API

Appendix A - Atom Standards Deviations

APP features not implemented in Atom API

Atom API differences from APP