Writing An Atom Feed
Sunday 23rd October 2005
Categories: Guides, Internet, Code
Writing the Basic Feed
A feed is generally made up of the feed itself, and the entries inside the channel. Before that, we need to define the file as an Atom 1.0 file. We do that using these two lines of code right at the beginning of the document:
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
You should also save the file with the extension .xml. If you are using PHP to dynamically generate the feed, you need to make sure the feed is sent as XML. To do this, add this line right at the beginning:
<?php header('Content-type: text/xml');?>
Next, we need a unique ID for the feed. The easiest way to create a unique ID is to use your website address. In case you no longer own the website in the future, you should also whack on the year. The format I use is this:
<id>tag:example.com/beans/,2005:1</id>
The two other required elements are the title and the time the feed was last updated. Both are fairly self explanatory, e.g.
<title type="text">Beans on example.com</title>
<updated>2005-10-22T21:20:45Z</updated>
Note that the title should be escaped, e.g. an ampersand should be written &. By adding the appropriate attribute, you can also use (X)HTML markup for the title, but I feel that it is better to keep the feed simple, and not overburden it with details such as formatting. If you really must use HTML formatting, the easiest way is to use XHTML, otherwise each tag must be escaped. For example:
<title type="xhtml">
<div xmlns="http://www.w3.org/1999/xhtml">
Beans on <b>example.com</b>
</div>
</title>
The attribute type, and its possible values text, html and xhtml, also apply to subtitle, summary, content and rights elements.
The date/time should be in the format: YYYY-MM-DDTHH-MM-DDtimezoneoffset, replacing timezoneoffset with either the timezone offset from GMT, or a Z if there is no offset. Possible examples are:
<updated>2005-10-22T21:20:45Z</updated>
<updated>2005-10-22T21:20:45+01:00</updated>
Note that the time that the feed was updated doesn't have to take account of the smallest changes.
There are a number of other elements that you can enter. There must be an author element unless every single entry has an author element. You can add as many author entries as you like. The format is:
<author>
<name>Bob Jones</name>
<email>bobjones@example.com</email>
<uri>http://example.com/~bobjones</uri>
</author>
You should include the name - the email address and URI are optional. In a similar way, you can add as many contributors as you like, e.g.
<contributor>
<name>Betty Jones</name>
<email>bettyjones@example.com</email>
<uri>http://example.com/~bettyjones</uri>
</contributor>
<contributor>
<name>Brian Jones</name>
</contributor>
Another element that you should have is a link back to the feed itself. It should read something along the lines of:
<link rel="self" type="application/atom+xml" href="http://example.com/beans/atom.xml"/>
Obviously, the href attribute should be changed accordingly. There are a few other link tags that you can include. The main other one is called alternate - this links to another source on the internet that provides the same information e.g. the front page of the website. The format is the same:
<link rel="alternate" type="application/atom+xml" href="http://example.com/beans/"/>
As you can see on this feed, the link goes to the front page.
Finally, the last two elements I'll be covering are the subtitle and rights. The subtitle is simply a short spiel about the feed, while rights covers the copyrights of the feed. For example:
<subtitle type="text">The latest news on beans.</subtitle>
<rights type="text">All content on this website is copyright (C) 2005, example.com/beans</rights>
Much of what was said about titles applies here. To repeat almost verbatim: Note that the subtitle and rights should be escaped, e.g. an ampersand should be written &. A copyright symbol can added by using ©. By adding the appropriate attribute, you can also use (X)HTML markup for the subtitle or rights, but I feel that it is better to keep the feed simple, and not overburden it with details such as formatting. If you really must use extra formatting, the easiest way is to use XHTML, otherwise each tag must be escaped. For example:
<subtitle type="xhtml">
<div xmlns="http://www.w3.org/1999/xhtml">
The latest news on <b>beans</b>.
</div>
</title>
So for the basic feed, you should now be able to make something similar to this:
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
<id>tag:example.com/beans/,2005:1</id>
<title type="text">Beans on example.com</title>
<subtitle type="text">The latest news on beans.</subtitle>
<rights type="text">All content on this website is copyright (C) 2005, example.com/beans</rights>
<updated>2005-10-22T21:20:45Z</updated>
<author>
<name>Bob Jones</name>
<email>bobjones@example.com</email>
<uri>http://example.com/~bobjones</uri>
</author>
<contributor>
<name>Betty Jones</name>
<email>bettyjones@example.com</email>
<uri>http://example.com/~bettyjones</uri>
</contributor>
<contributor>
<name>Brian Jones</name>
</contributor>
<link rel="self" type="application/atom+xml" href="http://example.com/beans/atom.xml"/>
<link rel="alternate" type="application/atom+xml" href="http://example.com/beans/"/>