Subject: a simple feed example

From: Henry Story <[email-masked]>
Date: Sun, 19 Sep 2004 20:30:50 +0200

I am working on exploring the possibility of using the Atom file format 
as the internal file format for BlogEd [0]. BlogEd is a client side 
blog editor, which currently stores its information in a not very 
extensible binary format. It currently has some ability to speak the 
MetaWeblog API, but I look forward to being able to implement the Atom 
API (when ready).  In order to help get a grasp on what this involves, 
I have extended on the example given in the latest draft Atom Format 
[1].

Here is the feed with 2 entries. Imagine this to be the latest feed 
archive.
Notice that the entry contains relatively little information.
(I don't think that according to the current spec it can contain less).

---------8<------------  myfeed-2.atom  -------------8<----------------
    <?xml version="1.0" encoding="utf-8"?>
    <feed version="draft-ietf-atompub-format-02: do not deploy"
     xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-02">
      <head>
        <title>Example Feed</title>
        <link rel="alternate" type="text/html"
         href="http://example.org/myblog.html"/>
        <link rel="prev" type="application/atom+xml"
         href="http://example.org/myfeed-1.atom"/>
        <modified>2003-12-13T18:31:02Z</modified>
        <author>
          <name>John Doe</name>
        </author>
      </head>
      <entry>
        <title>Atom-Powered Robots Now Under Control</title>
        <link rel="alternate" type="text/html"
         href="http://example.org/2003/myblog-2.html#entry4"/>
        <link rel="service.edit" type="application/atom+xml"
         href="http://example.org/2003/12/13/entry4.atom"/>
        <id>tag:example.org,2003:3.2397</id>
        <issued>2003-12-13T08:29:29-04:00</issued>
        <modified>2003-12-13T18:30:02Z</modified>
      </entry>
      <entry>
        <title>Atom-Powered Robots Run Amok</title>
        <link rel="alternate" type="text/html"
         href="http://example.org/2003/myblog-2.html#entry3"/>
        <link rel="service.edit" type="application/atom+xml"
         href="http://example.org/2003/12/12/entry3.atom"/>
        <id>tag:example.org,2003:2.127</id>
        <issued>2003-12-12T18:35:29-04:00</issued>
        <modified>2003-12-12T18:55:02Z</modified>
      </entry>
    </feed>
---------8<------------------------------8<----------------------------

In order to reduce the time taken to parse the files (so as to make the 
application
more responsive), we need to have small xml files. Atom's link element 
comes in very handy: the first feed points to the older myfeed-1.atom, 
with the following code

       <link rel="prev" type="application/atom+xml"
         href="http://example.org/myfeed-1.atom"/>

Below we have the older feed, which is very similar to the first one. 
It also
contains two entry outlines. The older feed points to the newer one 
with the

        <link rel="next" type="application/atom+xml"
         href="http://example.org/2003/myfeed-2.atom"/>

code.

---------8<------------  myfeed-1.atom  -------------8<----------------
    <?xml version="1.0" encoding="utf-8"?>
    <feed version="draft-ietf-atompub-format-02: do not deploy"
     xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-02">
      <head>
        <title>Example Feed</title>
        <link rel="alternate" type="text/html"
         href="http://example.org/myblog.html"/>
        <link rel="next" type="application/atom+xml"
         href="http://example.org/2003/myfeed-2.atom"/>
        <modified>2003-12-07T04:31:56Z</modified>
        <author>
          <name>John Doe</name>
        </author>
        </head>
      <entry>
        <title>Atom-Powered Robots threaten action</title>
        <link rel="alternate" type="text/html"
         href="http://example.org/myblog-1.html#entry2"/>
        <link rel="service.edit" type="application/atom+xml"
         href="http://example.org/2003/12/07/entry2.atom"/>
        <id>tag:example.org,2003:1.387</id>
        <issued>2003-12-07T04:28:39-04:00</issued>
        <modified>2003-12-13T04:30:02Z</modified>
      </entry>
      <entry>
        <title>Atom-Powered Robots demand higher voltage</title>
        <link rel="alternate" type="text/html"
         href="http://example.org/2003/myblog-1.html#entry1"/>
        <link rel="service.edit" type="application/atom+xml"
         href="http://example.org/2003/12/05/entry1.atom"/>
        <id>tag:example.org,2003:0.97</id>
        <issued>2003-12-05T12:19:05-04:00</issued>
        <modified>2003-12-13T12:35:02Z</modified>
      </entry>
    </feed>
---------8<------------------------------8<------------------------

In order to further reduce the parsing time of the above files, I have 
tried to remove
as much Entry content as possible from the Feed file. I would like to 
remove more, but I think the current spec requires what is in the 
examples. The Entry content itself is in its own file, pointed to in 
the feed by the

		<link rel="service.edit" type="application/atom+xml"
         		href="http://example.org/2003/12/05/entry1.atom"/>

which was the closest way I found of placing the content in an external 
file.
Below is an example entry file with simple text content (for the sake 
of keeping things simple)

---------8<-------------  entry1.atom  -------------8<--------------
    <?xml version="1.0" encoding="utf-8"?>
    <entry version="draft-ietf-atompub-format-02: do not deploy"
     xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-02">
        <title>Atom-Powered Robots demand higher voltage</title>
        <link rel="alternate" type="text/html"
         href="http://example.org/2003/myblog-1.html#entry1"/>
        <id>tag:example.org,2003:0.97</id>
        <issued>2003-12-05T12:19:05-04:00</issued>
        <modified>2003-12-13T12:35:02Z</modified>
        <content>
			The head robot of the APRA (Atom-Powered Robots Association)
demanded higher voltage for the day to day jobs of its members. In a 
statement
on his blog, he made the case that with the exponential growth in world 
blogging, finding entries was a lot more work than it used to be.
	   </content>
    </entry>
---------8<------------------------------8<--------------------------

The above has led me to the following thoughts:

1) BlogEd allows the author to illustrate every feed entry with a 
picture [3].
	Unless this can be represented by having more than one content - which 
the api
	allows for, but which may not represent the semantics I am looking for 
(I have
	heard that the different content elements have to represent different 
versions of
	the same content) - it seems that I need some type of extension. 
Perhaps a new tag
		<illustration href="illustration.jpg">
	is required.
	Another option is to have the content be xhtml and have a pointer to 
the content
     be inside the xhtml. But this would force me to parse the xhtml 
inside the content
	just to know that there is an additional attachment that I need to 
send along with
     the content, when sending the entry via the Atom API to a server.
	What should I do?

2) Pointing to the entry by reference from the feed, via the 
service.edit link element,
	seems to be close to what I want, but I am not sure this is exactly 
right.
	"service.edit" suggests that the url given is where it can be edited 
whereas I
	would like to limit it to GETing only.

3) Can urls be relative?  That would be really nice and would simplify 
the copying
	 these files from the local machine to the remote location. We 
currently do this
      using scp or ftp, and having exactly the same files locally and 
remotely would
      reduce the potential bugs a lot.

4) The above feed xml is very repetitive. Each feed contains both 
author and feed
	information that could more easily be placed in an external file, to 
be referenced
	by each feed file.

5) Imagine that at a later point the author makes a small change to an 
earlier entry.
	Perhaps he fixes a spelling mistake, or perhaps an externally 
referenced resource
	has moved and part of the html needs fixing. Perhaps we change 
something in
	entry1.atom in our example. So the head feed file will need a new 
<entry> element,
	to nudge readers to download the new version. Would it be more honest 
to place the
	altered entry in a new file, rather than overwriting the old one, in 
order to keep
	the archive feed files pointing correctly to the entry version they 
had always been
	pointing to?

Thanks for helping me work out this simple example. Perhaps this will 
be very helpful to others looking for an entry into this burgeoning 
standard.

Henry Story

[0] https://bloged.dev.java.net/
[1] http://www.ietf.org/internet-drafts/draft-ietf-atompub-format-02.txt
     
http://www.ietf.org/internet-drafts/draft-ietf-atompub-protocol-01.txt
[2] http://bblfish.net/work/atom-owl/2004-08-12/	Especially the feed* 
files
[3] see for example: http://today.java.net/jag/