AtomForWikis

MeatballWiki | RecentChanges | Random Page | Indices | Categories

It's probably time to start thinking about how Atom will work with wikis. The Atom people have started discussing this:

I am assuming that, just like everything else, the various wiki engines will be slow to implement Atom support and the various wikis will be slow to upgrade. So I am building Atom support into WikiGateway. So, if you have an Atom client, and you want to target a wiki server which doesn't support Atom, you would send your Atom request to a WikiGateway instance which would interface with the target wiki for you. This functionality currently works in WikiGateway (code is available) (except for "COMMENT" support, which wikis don't do anyway), but I need to tidy up the code a bit before a real "release".

-- BayleShanks

From Sam Ruby's weblog

I copied, with permission, some of the following thread from [Sam Ruby's blog entry] (only the parts spoken by Sam Ruby and me so far, pending permission from other participants):

Source wiki markup vs. html

This is fairly obvious, but needs to be spelled out: the syntax for editing Wikis not the syntax used for display. This means that there needs to be separate mechanisms for retrieving either the original source vs the formatted source. This can be achieved as simply as having different URLs for each function. -- Sam Ruby

Joe Gregorio agreed.

Sounds good to me. I agree that the spec needs to mention somewhere that such-and-such a URL is for the "source", when such a distinction exists. -- BayleShanks

Danny Ayers felt that the server-interpretation of links could be problematic. He feels that maybe the client should just send the HTML source rather than the wiki markup source. He points out that a WSYIWYG wiki client would be a natual choice in this case.

New page creation

The Wiki edit model more closely corresponds to using HTTP PUT for creating new pages. In other words, the client determines the URL. Some webloginging systems support this, though more commonly the server determines the URL. However, I do expect that having the client specifying the URL will become more common with photoblogs and other mechanisms involving images. I suspect that some additional information should be added to the introspection file so that clients can determine server policies and capabilities in this reguard. -- Sam Ruby

Joe Gregorio feels that in order to create a page, Atom clients should first GET the nonexistent page, and then PUT the first version. This mirrors what wiki users do today.

: Probably true. What are the benefits you see of going outside the current interaction model?

The words interaction model sets of alarm bells in my head. Those words, particularly in conjunction with the notion of implicit state and coordination are sure to invite a series of flames from those of the REST persuasion.

One could perhaps wave these concerns off as "merely theoretical", but they have pragmatic implications. In particular, they impose greater requirements on the clients to have more knowledge of the target application. In this case, they can require a generalized web editing application to be aware that the target is a wiki, and therefore a different series of steps are required to create a page than for a weblog. -- Sam Ruby

: I agree with Sam. I don't think there is a need to ask the client to attempt a GET on a new wiki page before PUTing it, just because that is what users do today. -- BayleShanks

EditConflict detection

MoinMoin inserts a hidden "datestamp" form field on HTTP POST to ensure that people don't overwrite each other's changes. I believe that other wiki software employs similar tactics. What this would correspond to in Atom is requiring that the atom:modified date be echoed back on the POST request. If it doesn't match, the request is rejected. This should be spelled out in the API. -- Sam Ruby

Joe Gregorio feels that the following would be sufficient: "elements or attributes in an Atom representation of an entry SHOULD NOT be dropped between the GET and the PUT, and that servers MAY reject such PUTs if elements or attributes are missing."

I'm concerned specifically about the modified element. My concern isn't that clients will remove this element, it is that clients will "helpfully" choose to update it. I see one of two possible paths to take on this one: either declare that modified is always set by the server and state that PUT requests MUST NOT contain this element, or state that clients MUST repeat the original value of the modified element on PUT requests that act as a replacement. -- Sam Ruby

Etags for EditConflict detection

: Ken MacLeod? suggested HTTP ETags for doing EditConflict detection. Michael Smith agreed and provided [this link] which explains the method. It was noted that If-Modified-Since might be another idea, but it has a one-second race condition.

 > Re. datestamps, note that ETag/If-Match can be used with PUT.

Unfortunately, I have yet to find a single Wiki that supports ETags. I'm torn. My feeling at the moment is that Atom should be defined in a way that enables and perhaps even encourages the use of ETags for this purpose, but does not require such. Alternatives such as If-Modified-Since and "hidden" elements should also be supported. -- Sam Ruby

: re: EditConflicts?

: I think we should go with the Strong ETags / If-Match approach.

: If an Atom client is going to make an Atom request to a wiki, either the request will have to go through a gateway like WikiGateway, or the wiki is going to have to add Atom support as a feature.

: So it doesn't matter that wikis don't do ETags.

: Different wiki clients want to use version numbers or modified dates or both, but the Atom protocol can use ETags or whatever the "best practices" HTTP field is for this sort of thing. WikiGateway can translate, or the wiki servers can learn to use the different field when they add Atom support. The process that wikis are trying to use the modification date and version numbers for maps onto ETags, so I think they will be sufficient. -- BayleShanks

What concerns me most about ETags is that it depends on the correct operation of clients in order for the server to maintain a coherent version history. That would invite mischief. So the only way I think that going with an ETag based approach make sense is if they are REQUIRED on PUT requests.

BTW, I don't buy the argument that because there must be a gateway or explicit Atom support that "it doesn't matter if wikis don't do ETags". That reasoning can be used to justify almost any feature.

What I would most like to see is an API which is as common as possible to as wide of a set of use cases as possible - first and foremost being weblogs. For single user weblogs, the requirements for coherency is versioning are quite different. -- Sam Ruby

: BTW, I don't buy the argument that because there must be a gateway or explicit Atom support that "it doesn't matter if wikis don't do ETags". That reasoning can be used to justify almost any feature.

: That's true, it could. But, right now there are a number of wikis, most of which basically use some sort of "Unreserved Checkout" scheme, to use the W3C article's terminology, and each of which has a slightly different way of doing it. As you pointed out,

: As to versioning, the names and formats of the attributes vary (wpEdittime, nextver, version_mark, revision, editversion, datestamp, ...), but the approach is common to all wikis that I have seen, and is an alternative to explicit locking, and IMHO bears special mention.

: Your "modified" proposal means coercing all of these different fields into the "modified" field. This doesn't seem different from coercing them into an "ETags" field or anything else.

: And, the semantics of fields like "modified" could get confusing: as you pointed out, it may surprise developers to find that they aren't supposed to update a field named something like "modified" when they modify content. "ETags" won't be surprising this way.

: So, basically, if you are going to choose a single field and say "this is the field that wikis should use to deal with Edit Conflicts", you can make that an "Etags" HTTP field as easily as a "modified" XML field. Either way you must depend on the client treating that field correctly. But the implied semantics of a "modified" field may encourage people to use it for something else than detecting edit conflicts. In contrast, I had never heard of an Etag before today (so I probably wouldn't abuse one), but upon reading that link, its semantics seem to match exactly what wikis are using the datestamp, etc. fields for: a unique identifier which distinguishes different revisions of the same resource. -- BayleShanks