Atom Webfeed Basics
This page is a basic tutorial on the Atom webfeed format.
There is a webfeed format called Atom. Atom is based on XML, and is a more correct and well designed format than the more popular RSS format. One major user of Atom is Google.
Here's a Atom sample template:
<?xml version="1.0" encoding="utf-8"?> <feed xmlns="http://www.w3.org/2005/Atom" xml:base="http://xahlee.org/Periodic_dosage_dir/"> <title>Xah's Blog</title> <subtitle>Ethnology, Ethology, and Tech Geeking</subtitle> <link rel="self" href="http://xahlee.org/Periodic_dosage_dir/pd.xml"/> <link rel="alternate" href="http://xahlee.org/Periodic_dosage_dir/pd.html"/> <updated>2006-09-11T02:35:33-07:00</updated> <author> <name>Xah Lee</name> <uri>http://xahlee.org/</uri> </author> <id>http://xahlee.org/Periodic_dosage_dir/pd.html</id> <icon>http://xahlee.org/siteicon.png</icon> <rights>© 2006 Xah Lee</rights> <entry> <title>Batman thoughts</title> <id>tag:xahlee.org,2006-09-09:015218</id> <updated>2006-09-08T18:52:18-07:00</updated> <summary>Some notes after watching movie Batman.</summary> <content type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml"> <p>I watched Batman today …</p> <!-- more xhtml here --> </div> </content> <link rel="alternate" href="pd.html"/> </entry> </feed>
You can use the above as a template. The file name should have a suffix of “.xml” or “.atom”.
The MIME type should be
Few things of note:
The file's header contains standard info such as: blog title, author info, copyright info, blog URL, (unique) id for this blog. Then, the main body is made of several “entry”. Each entry has a title, id, timestamp, summary, perm link URL, and full content (optional).
link ref="self" … should point to the URL of the file itself.
link ref="alternate" … should be the HTML URL for this feed.
Note the date format. It must strictly be of this form:
yyyy-mm-ddThh:mm:ss±hh:mm. The T in the middle is literal. It is used as a separator of date and time. The last part
±hh:mm is your local time offset to
Coordinated Universal Time
Now, in the “entry” section, the “content” is optional. The
link ref="alternate" should be the HTML path of the full article.
id tag is very important. It needs to be unique and unchanging across ALL atom entries in the universe, and it must be in a URI format. What i've done here, and you can follow, is this format:
tag:, then your domain name, a comma, then a date string yyyy-mm-dd, then a colon, then unix epoch seconds.
If two entry might be made in the same second in a large organization, then you might also want to add author name.
Webfeed Reader Bug on Relative Link
I just discovered bugs in rss aggregator in google.com, my.yahoo.com, my.msn.com .
For my.msn.com, it won't understand validated atom 1.
For google.com, it won't understand relative links unless you have xml:base in your atom.xml.
For yahoo.com, it won't understand relative links, period, regardless whether you have xml:base.
According to the Atom spec tools.ietf.org rfc4287 on relative links which defers to http://tools.ietf.org/html/rfc3986#section-5.1.1, a atom doc without explicit “xml:base” should take the base as the path the current URL. (just as with HTML files)
So, it seems to me google's behavior is wrong.
Google's feed reader fixed the relative link bug.
recently, Christopher Wellons's feed reader elfeed (https://github.com/skeeto/elfeed) also had this problem. (See bug https://github.com/skeeto/elfeed/issues/37) It has been fixed since.
Adding IE Webfeed Button Support
In IE 7, released in 2006, there's a webfeed button in the toolbar. If user visits a page that has a corresponding feed, the button will light up, allowing user to click on it to view the feed, or subscribe. (IE is currently at version 8, released in 2009)
However, developers need to add a link to their page in order for this button to work. If you are using ATOM, the link is like this:
<link rel="alternate" type="application/atom+xml" title="Xah's Web Programing Blog" href="http://xahlee.org/js/blog.xml">
〔Windows RSS Publisher's Guide (work-in-progress) @ http://blogs.msdn.com/rssteam/articles/PublishersGuide.aspx〕