AtomAPI Quick Reference

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

URI Type	HTTP Method	Content Type	Return values
Post	POST	AtomEntry	Returns an Edit URI in the Location: header.
Edit	GET, PUT, DELETE	AtomEntry
Feed	GET	AtomFeed

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'/>

<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>

There are textboxes around the examples which make the difficult to read and/or print. Could you fix this? Thanks.

Posted by Dan on 2003-11-06

Dan,
What browser/operating system are you using?

Posted by Joe on 2003-11-06

Same thing here using Mac OSX 10.2 and Safari 1.0. The code samples are in narrow text boxes showing less than half the code horizontally, with a horizontal scroller.

Posted by Mercutio on 2003-11-06

How does that look now?

As for printing, I only specify CSS for a media type of "screen" so the content should print completely unstyled.

Posted by joe on 2003-11-06

Better. The code boxes are right aligned with the text of the post; they resize as the window resizes. Now the longer code lines spill outside the boxes into the space below the sidebar.

Thanks for your work on Atom.

Posted by Mercutio on 2003-12-02

You wrote: "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."

I hope you'll forgive a stupid question, but I'm trying to figure out how all this works so I can integrate Atom into a project I'm working on. I don't know a thing about RSS, but I'm trying to learn.

The above sentence makes it sound like they'll be a single address for posting to a site. What about sites with 100s of weblogs? Still one address for posting? Or one per weblog?

Posted by Lawrence Krubner on 2004-03-19

Site in this case would be a weblog, so yes, there would be a seperate URI for each weblog to post to.

Posted by Joe on 2004-03-19

Hi and thanks this is great stuff

Just a couple of comments :

1) you have 2 < 4 in the atom entry content example, is the '<' allowed instead of '<' or is that a typo?

2) Is overwriting post supported in addition to the put paradign. That is if one posts to and existing post uri and id purpously to edit an existing post as opposed to using put inorder to edit an entry?

regards
Al

Posted by Alan Wood on 2005-10-11

I also notice in the draft 5 doc about collections documents :
<?xml version="1.0" encoding='utf-8'?>
<app:collection xmlns:app="http://purl.org/atom/app#">
<app:member-type>entry</pub:member-type>
<app:uri-template>http://example.org/{index}</pub:uri-template>
<app:uri-template>http://example.org/{daterange}</pub:uri-template>
</app:collection>

Looks like a mix up between the app and pub namespaces.
I wish I could find and easier way to convey the typo , but I do not with to subscribe to yet another mail list in order to do so, hence the mention here. Maybe there should be an atom blog where I could do so? I rather new to it (atom).

regards
Al

Posted by Al on 2005-10-11