Today on IRC Sam Ruby challenged some of my preconceived notions of a weblog editing API. In particular he asked the very simple question, "How do you find the entry you want to edit".
Having a pre-conceived notion of blogs having a linear structure, I hadn't really thought too hard about that. But both Blosxom and Wikis don't necessarily have that linear structure. Blosxom allows creating entries with a directory structure, with no predetermined concept of order among the individual entries. Sure, you could sort by date or by title, but traversing a potentially deep directory structure and visiting each file just to find the ten most recently updated entries is computationally expensive.
Wikis, on the other hand, offer a different challenge and really open up the possibilities. First, I had never even considered applying the AtomAPI to a Wiki. Having deltas off a wiki show up in my aggregator, and then being able to edit that page directly, without having to open the page in my browser, seems like a killer application of the AtomAPI. It would certainly make tracking the Atom wiki easier.
The other reason the I hadn't really thought too hard about finding an entry is that in Bulu, I cheat. Bulu is the server-side Python software I use to manage my sites, and it uses content negotiation. That is, the same URI that is used for the HTML form of the entry is the same URI used to get the XML version of the entry. Don't do this. In the process of implementing
Like I said, conneg isn't easy to implement and has it's drawbacks, but there is a simple way to enable the same functionality with out using conneg. The link tag. Place a link tag in the head of the page that contains the entryURI. That would enable any client and server to support the same drag-n-drop functionality by parsing the 'head' and looking for link tags of the form:
< rel="service.edit" type="application/x.atom+xml" href="entryURI goes here" title="A name/desc of what you would be editing">
And to mirror that same functionality an Atom feed could have an entry level element
edit-uri that pointed to the same entryURI.
Now with that link tag in place you have some real opportunities for cool stuff to occur, for example you could build a browser add-on that displayed an 'edit this page' button for every web page that had such a link tag. That feature in particular would really help in wikis. Feed aggregators could also provide the same functionality. More importantly this "solves" the initial problem, "How do you find the entry you want to edit", and solves it in a very webbish way by pushing the answer back into the browser where the navigational possibilities are richer than anything that could be pre-built into any API.
Update: Please see the follow-on article: Deconstructing the AtomAPI.