How To: Create an Atom Feed

Most people are already familiar with RSS and RSS2 feeds for content syndication. ATOM doesn’t appear to be as popular yet, however it is catching on more and more. ATOM 1.0 is similar to RSS in a lot of ways, is a bit simpler, and is very easy to generate. We’ll walk through creating a simple ATOM 1.0 feed from scratch.

XML Declaration

Since an ATOM feed is an XML document, you must declare it as such in the first line of your feed:

<?xml version="1.0" encoding="utf-8"/>

ATOM Feed Information

The root element in your ATOM feed is the “feed” element, which must contain the following required elements:

<atom:feed xmlns:atom="http://www.w3.org/2005/Atom">
  <atom:id>unique identifier (such as your URL)</atom:id>
  <atom:title>site title</atom:title>
  <atom:updated>w3c date of last update</atom:updated>
  <atom:link href="URL of this document" rel="self"/>

  <atom:author>
    <atom:name>Your Name<atom:name>
    <atom:email>Your e-mail address<atom:email>
  </atom:author>

</atom:feed>

Your atom:id should be a long-term globally unique identifier for your site. If you own your domain you’re okay to use your URL (I do), however I’ve also seen examples where they use some globally unique URN code.

Feed Entries

Finally, you need to add your content inside the feed element. An ATOM entry corresponds to an item in RSS. Each entry contains contains the basic information such as title, id and time, as well as a summary and the full content of your article. Each item will look like this:

<atom:entry>
  <atom:title>Aritcle Title</atom:title>
  <atom:id>Unique story id</atom:id>
  <atom:updated>w3c date of story</atom:updated>
  <atom:link href="Your story's permalink"/>

  <atom:summary>Short summary of your post<atom:summary>
  <atom:content type="html">
    <![CDATA[ content of your post ]]>
  </atom:content>
</atom:entry>

Just like your feed’s ID, an entry ID should be a globally unique identifier for your post. I use my post’s permalink as my ID, but again I’ve also seen examples that use some URN ID code. An entry summary is not required, however it’s strongly recommended for accessibility reasons. I use the first 20 words of my article as the summary. Finally, your article content. The content type may be either “html” or “text”. If you choose “html”, I would recommend putting the content inside a CDATA section.

If you use tags (or even categories) on your blog, you can add your tags to the atom feed as categories. Doing so allows readers to pick and choose which of your content they’re interested in, and subscribe to just those parse of your feed. For each category you want to mark an entry with, just add:

  <atom:category term="category"/>

To the atom entry element.

Validate!

You can validate your feed using Feed Validator.

Other useful information

See Pete’s post on adding css to rss feeds. The same technique could be applied to your ATOM feed for stylish viewing in a browser.

You can add ATOM Feed auto discovery to your site by adding the following line to your HTML header:

<link rel="alternate" href="your atom url" 
                      type="application/atom+xml"/>

For more information on the ATOM syndication format, check out the ATOM Syndication Format specification.

Update (Nov 12 2005)

Roger Benningfield points out a few minor corrections to things I stated or implied in this post:

The namespace prefix is optional, as it usually is in XML :). I’m a fan of being explicit.
atom:updated isn’t necessarily the time the last post was updated. I didn’t mean to imply this was a rule — but damned if it shouldn’t be.
Roger states that the feed-level self link is optional. FeedValidator issues a warning if it is missing, and it is strongly advised that you include it.
atom:content can be any valid mime-type. I didn’t know this when I wrote this post, that opens up a lot of really cool syndication possibilities using Atom.