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 conneg I discovered some fairly serious drawbacks. The one positive side-effect of this decision is that in Pamphlet, the client side tool I use to edit my sites, I can just drag-n-drop a URI from the browser to Pamphlet and begin editing. Pamphlet knows to GET the entry from a dropped URI. When I am done editing Pamplet PUT's the edited entry back to the same location.

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.

Bulu is the server-side Python software I use to manage my sites, and it uses content negotiation.


...

Don't do this. In the process of implementing conneg I discovered some fairly serious drawbacks.

What are these exactly?

Posted by Myers Carpenter on 2003-09-06

A combination of Wiki and AtomAPI is indeed an extremely compelling idea (not to mention being true to Tim Berners Lee's original conception of an editable web). I've been toying with the idea of using an Atom "client" as a means of updating a knowledge-base like website - something Wiki-like, and I like what I see/imagine.

This is one of the reasons I've tried to spend some time over the last few weeks reading up about Mozilla application development - since it seems to me to be the natural environment to build an Atom client which doubles as a web content editing system, and as you so elegantly put it: pushing back to the browser what it does well - navigating the web.

Your idea is giving me that warm fuzzy feeling.. the sorta "this is getting exciting" feeling.

(Now if someone could make more hours in  a day....)

Posted by Isofarro on 2003-09-06

Another option would be to provide a link to the Atom representation of the page, and not a specific "edit" link to this page. You could then add in the Atom entry whatever metadata you need.

Posted by Ziv Caspi on 2003-09-06

Ziv,
  In case it wasn't clear, the link tag is pointing to a URL that contains a representation of the page as an Atom entry. HTTP GET to get the entry, HTTP PUT to update the entry.

Posted by Joe on 2003-09-06

Myers,
  I have since written up the problems I have seen with Content Negotiation here:

http://wellformedweb.org/news/WebServicesAndContentNegotiation

Posted by Joe on 2003-09-06

I like the way this is going! Wikis are a good example of what can be done with the same basic infrastructure as blogging tools. To generalise that out to what is effectively an editable knowledgebase, which can have all kinds of (possibly editable) views leaves the door wide open for applications like bugtracking or product catalogues. IMHO the easiest way of facilitating this would be with the RDF model, but it should be feasible for the AtomAPI to operate orthogonally to whatever model is used, as long as all the appropriate metadata is available for querying by whatever means (i.e. let the service figure out which entries you're likely to be interested in).
I would have thought conneg would have made a neat shortcut for common operations, but your notes to raise some big doubts...

Posted by Danny on 2003-09-08

I'm working on a program that would act as a bridge between wikis and Atom. See

http://interwiki.sourceforge.net/cgi-bin/wiki.pl?WikiGateway

Posted by Bayle Shanks on 2003-10-18

The application I am working on requires the ability to retrieve all or some of the content from a blog (preferably a date range) like all of 2002 entries.  This would be a pain in the butt and very network intensive with the need to do next/previous links.  I hope I am misreading some of this stuff but having no search ability and having to make hundreds of network requests to get data sounds bad.

Also I can see a lot of blog clients wanting to be able to load in a full blog so that editing older entries can be done.

Am I missing something?

macro

Posted by macro on 2004-03-08

macro,
  It's not as bad as it seems because, while there hasn't been as much attention focused on it as the feed format and API, an archival format in Atom is part of the charter:  http://www.intertwingly.net/wiki/pie/RoadMap

Posted by Joe on 2004-03-08

link suggestion

Posted by ramona on 2005-08-15