AtomEnabled ^beta

The current revision of the AtomAPI is contains quite a few changes from previous revisions. All of those changes have been talked about seperately, but when put together represent a fairly large change to the API. Here is Quick Reference for the AtomAPI which also highlights those changes.

The URIs in the draft AtomAPI RFC are not normative, they are examples. The draft RFC isn't about specifying the form of the URLs that are to be used. Yes, there are guidelines you should follow when creating URIs, but those are just general guidelines. That is an important document and if you're creating server side software you should know it already.

In the end, it's the server that controls the URI space for that domain. Now, for convenience that space may be mapped to a file system hierarchy, but again, there's no requirement for that to be true. So what does the RFC specify? It lays out the formats of the files that can be returned, and the actions that can be performed on the URIs. Note that URIs are embedded in some of those formats. That embedding, that intertwingling of format and URI, is the crux of hypertext, and we are using HTTP as our protocol, the Hypertext Transfer Protocol. Here then is an abbreviated description of the AtomAPI as it stands today, with all the example URIs contracted into short names. Outlined first are the different types of URIs the AtomAPI deals with. Different types of URIs are distinguished by the methods that are allowed to act on them, their actions, and the content-types that they accept.

Types of URIs

Several things are important to note here. First is that both weblog entries and comments on those entries are both created using a Post URI. Now they are probably going to be different URIs, but they are the same type of URI, i.e. a URI that accepts a POST with a body of a filled in Atom Entry and as a consequence creates a new resource based on that Entry. How to discover the types of URIs and what they are used for is discussed later.

All of the discovery uses a link tag. The link tag from HTML will be used in (X)HTML, and the same tag will be used in the Atom format, with the restriction the value of the rel attribute is case sensitive.

Post

Purpose

The Post URI is used to create entries. These can be either full entries as in a weblog post, or they can be comments. The client POSTs a filled in Atom Entry to this URI.

Finding

For creating a new site Entry, the link tag is used. Note that a link tag is used in both HTML and in the Atom format. A link tag of the following format points to the Post URI for a site. In HTML the link tags are always found in the head element, while in Atom they may appear as children of the Feed and entry elements. In the case of Post, the link tag is found in HTML and as a child of the Feed element only.

<link rel="service.post"
   type="application/x.atom+xml"
   href="URI for Posting goes here"
   title="The name of the site.">

Note: Multiple link tags may appear together and can be distinguished by having different 'rel', 'type' and 'title' attributes.

Edit

Purpose

The Edit URI is used to edit an existing Entry. To edit the Entry the client does a GET on the URI to retrieve the Atom Entry, it then modifies the Entry and then PUTs the Entry back to the same URI. Use the DELETE method on the URI to remove the Entry. Note that an Entry could be either a full Entry on a site, or a comment.

Finding

A link tag in either HTML or Atom of the following form will point to the URI for editing an Entry.

<link rel="service.edit"
   type="application/x.atom+xml"
   href="URI that handles editing "
   title="Desc/title of Entry.">

Feed

Purpose

The Feed URI is used to retrieve an Atom feed. Note that the feed may contain just Entries for syndication, or may contain additional link tags so that it may be used for browsing/navigating around to other Atom feeds.

Finding

A typical feed for syndication would be indicated by a link tag of the form:

<link href='URI of feed goes here'
   type='application/x.atom+xml'
   rel='feed'
   title='A nice descriptive title'/>

If a feed contains extra link tags for navigation, such a feed might be supplied specifically for a weblog publishing client to use, then it is of the form:

<link href='URI of feed goes here'
   type='application/x.atom+xml'
   rel='feed.browse'
   title='A nice descriptive title'/>

Or

<link href='URI of feed goes here'
   type='application/x.atom+xml'
   rel='prev'
   title='A nice descriptive title'/>

AtomEntry

<entry xmlns="http://example.com/newformat#" >
  <title>My First Entry</title>
  <summary>A very boring entry...</summary>

  <author>
    <name>Bob B. Bobbington</name>
    <url>http://bob.name/</url>
  </author>

  <issued>2003-02-05T12:29:29</issued>
  <created>2003-02-05T14:10:58Z</created>
  <modified>2003-02-05T14:10:58Z</modified>

  <link rel="alternate" type="text/html"
    href="http://example.org/reilly/2003/02/05#My_First_Entry"/>

  <id>urn:example.org:reilly:1</id>

  <content type="application/xhtml+xml" xml:lang="en-us">
    <p xmlns="...">Hello, <em>weblog</em> world! 2 < 4!</p>

  </content>

</entry> 

AtomFeed

<?xml version="1.0" encoding="iso-8859-1"?>
<feed version="0.3" xmlns="http://purl.org/atom/ns#">

  <link rel="next" type='application/x.atom+xml'
     title="Next 20 Entries" href="http://.."/>
  <link rel="prev" type='application/x.atom+xml'
     title="Previous 20 Entries" href="http://.."/>
  <link rel="comments" type='application/x.atom+xml'
     title="Last 20 Comments" href="http://.."/>
  <link rel='service.post' type='application/x.atom+xml" 
     title="Create a new post on intertwingly.net" href=".."/>

  <entry>
    <id>http://example.org/blog/1630.atom</id>

    <link rel="alternate" type="text/html" 
       href="http://example.org/blog/1630.html" />

    <link rel="service.post" type='application/x.atom+xml' 
       href="/blog/1630.atom-new-comment" title="Add a comment."/>

    <link rel="comments" type='application/x.atom+xml' 
       title="Comments on Entry 1630" href="/blog/1630.atom" />

    <link rel="service.edit" type='application/x.atom+xml" 
       href="/blog/1630.atomapi" />

    <title>One year ago today...</title>

    <content type="application/xhtml+xml" mode="xml">
      <div xmlns="http://www.w3.org/1999/xhtml">Microsoft
      <a href="http://www.intertwingly.net/blog/945.html">
      inhaled a blogger</a>.&#160; Now it looks like
      he is attempting to
      <a href="http://www.razorsoft.net/weblog/2003/10/28.html">
      resurface</a>...
      </div>

    </content>

    <issued>2003-10-29T20:52:57-05:00</issued>
    <modified>2003-10-29T20:52:57-05:00</modified>
  </entry>

  <entry>
    <id>http://example.org/blog/1628.atom</id>
    <link rel="alternate" type="text/html" 
       href="http://example.org/blog/1628.atom" />

    <link rel="service.post" type='application/x.atom+xml' 
       href="/blog/1628.atom-new-comment" title="Add a comment"/>

    <link rel="comments" type='application/x.atom+xml' 
       title="Comments on Entry 1628" href="/blog/1628.atom" />

    <link rel="service.edit" type='application/x.atom+xml" 
       href="/blog/1628.atomapi" />

    <title>Is &lt;content&gt; required on a POST?</title>

    <content type="application/xhtml+xml" mode="xml">

      <div xmlns="http://www.w3.org/1999/xhtml">
        I've kicked off what I intend to be a series of
        discussions leading up to the creation of a
        validation test suite for Atom implementors
        with the following question on the
        <a href="http://www.imc.org/atom-syntax/index.html">
        atom-syntax mailing list</a>:
        <a href="http://www.imc.org/atom-syntax/mail-archive/msg00908.html">

        Is content required on a POST</a>?
      </div>

    </content>

    <issued>2003-10-29T05:24:12-05:00</issued>
    <modified>2003-10-29T05:24:12-05:00</modified>

  </entry>

</feed>