Deconstructing the AtomAPI

Joe Gregorio

Yesterdays idea of applying the AtomAPI to wikis got me thinking about the AtomAPI more generally. The idea of using a link tag on the web page to be edited points to idea that some parts of the AtomAPI could be eliminated. So let't take some time and push that idea to its logical extreme to see how small the AtomAPI could be made.

N.B. What follows is a thought experiment. I am not proposing this as revision 8 of the AtomAPI, it is merely a thought experiment to flesh out some ideas and to generate some discussion.

So from yesterdays discussion we know that the search facet can be removed from the API in favor of letting the browser be used to naviagte the site in choosing which page to edit. In place of the seach facet each page has a link tag of the form:

<link rel="service.edit" type="application/x.atom+xml" 
      href="entryURI goes here" 
      title="A name for what you would be editing">

And that entryURI is what you do GET, PUT and DELETE against to update that entry.

That's just a quick re-cap from yesterdays discussion. Now let's move forward and look at the rest of the facets in the AtomAPI. The CommentAPI portion of the AtomAPI already works in a similar manner, i.e. a link tag on HTML pages points to the commentURI so nothing there needs to change.

<link rel="service.comment" type="application/x.atom+xml" 
      href="commentURI goes here" 
      title="A name for what you are commenting on.">

That leaves the facets for creating an entry, editing preferences, and editing templates.

Editing templates could work the same way as editing an entry. That is, create a web page for each template. On that page is a link tag to an entryURI. Doing a GET on that entryURI gets you an Atom representation of that template. You can then edit and PUT that representation back to update it.

Preferences are a bit out of place, so for now, as part of the thought experiment, we'll just drop them. Wasn't that easy?

The very last facet of the API is for creating of a new entry. That could be handled by putting a link tag on the main page with the URI that you POST to to create a new entry.

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

If you've followed along this far then you realize the the Introspection file has now been orphaned and can be dropped. That's really suprising that so much of the AtomAPI can go away with very little loss in functionality, i.e. only the preferences part of the API has been dropped. So in summary we are left with three link tags and a single file format.

  1. Create - A link tag that points to the URI that you would POST an Atom Entry to to create a new entry.
  2. Edit - A ling tag that points to the entryURI for the page you are viewing. Use GET, PUT and DELETE to update. Works for both entries and templates.
  3. Comment - A link tag that points to the URI to POST comment entries to.

I know that would certainly make the RFC easier to edit, it leverages the current HTML infrastructure better, and opens up the API for things like editing Wikis. It seems a bit extreme to me, but elegant, and I'd really like to hear what you think of this.

Wouldn't that bind the AtomAPI a bit too tight with HTML?  For instance, what if I wanted to use the AtomAPI to work on Atom entries that would never be rendered as pure HTML?  For instance, suppose you were a syndication, where your entries showed up on other people's blogs, but never on its own blog.  Then where would I look for those links?

Posted by Seairth on 2003-09-07

  In the case of your last example, each Atom entry could have <edit/> element that pointed to the entryURI.

  Beyond that, well, I don't know what kinds of work should be put into making a web content editing API work for content that's not on the web.

Posted by Joe on 2003-09-07

In general, I am for this idea, with one caveat: I continue to be skeptical about the cost/benefit value of PUT and DELETE.

Carrot Vs Orange?  There is a third alternative...

Posted by Sam ruby on 2003-09-08

Suppose, hypothetically, that I wanted to replace comment how would that be done with this approach?

Posted by Sam Ruby on 2003-09-08

FYI: The pingback specification defines an HTTP header as an equivalent to the link element for autodiscovery.

Just more food for thought.

Posted by Sam Ruby on 2003-09-08

So are you saying that a web content editing API must work with HTML in order to be "on the web"?

Posted by Seairth on 2003-09-08

  Re: PUT. I would be fascinated to hear your views on WebDAV, which you were involved in. Yes, WebDAV, which not only uses PUT and DELETE, but which also invented new HTTP status codes and also invented new HTTP verbs.

Posted by Joe on 2003-09-08

Short answer is that WebDAV has not taken the world by storm.  But I will be taking a closer look again at it tomorrow...

Note the #2 name on that list can also be found on  And both of our names are on

Posted by Sam Ruby on 2003-09-08

Re. Seairth's comment: maybe it's serendipity that allows an HTML representation to handily have a "known" editable resource at another URI.  Where most other resources don't have or need different representations and therefore don't need content negotiation.  It's those resources we need a solution for "finding" so we can act on them.

Or maybe we don't.  We can just "Edit this URI."

Posted by Ken MacLeod on 2003-09-08

  No, I am not saying it requires HTML, look at the method I gave for finding the same information via an Atom feed. The key is that both the HTML and the Atom feed are on the web.

Posted by Joe on 2003-09-08

I like it. In general, I'm all for extremism.

Posted by Aaron Swartz on 2003-09-21

comments powered by Disqus