1 post tagged “microformats”
When I originally implemented support for subscriptions and preferences in Cosmo's Atom subsystem, I represented their info in sort of strange ways. Subscription entries had a couple of extension elements that specified the sub's collection UUID and ticket key, the entry's title was the sub's display name, and the entry had no content (which isn't technically legal). Preference entries used the title element to specify the preference key and included the preference value as text content. The representation styles weren't symmetrical with each other nor with that for items (which are completely represented by an external format like JSON or EIMML and included wholly in the entry's content element). The client programmer had to learn all these different styles, which is confusing and sucky, and write different framework code for each. Even worse, by not treating subs and prefs as media, we couldn't do things like POSTing and PUTting subs and prefs directly into their collections or GETting them directly out of their collections without wrapping them in Atom entries.
Let's take a step back and think about why we're actually using APP in Cosmo. APP is basically a set of rules layered on top of basic REST principles for allowing the server to create, update and delete resources. When the client wants to create or update a resource with APP, it encloses a representation of the resource inside an Atom entry document. The idea with most APP implementations is that the entry meta-data will actually be useful in some way. But for Cosmo items, subscriptions and preferences, it tends not to be. These resources don't have client-modifiable attributes that correspond to Atom entry data like id, owner, updated. So, modeling them as media resources makes a lot of sense. This is almost like not using APP at all, except for the fact that Cosmo follows the general rules for control and publishing (sections 4.3 and most of 5) and provides service documents (section 5.1), which I think are the two most important parts of the document. This means that Cosmo clients can be written with standard Atom and APP libraries rather than built on top of lower level HTTP libraries.
We do care about Atom entry (and feed) documents when the server is sending data to the client (because the documents include the links to related resources that provide the property of the Resource-Oriented Architecture that RESTful Web Services calls "interconnectedness") but not so much when the client sends data to the server. This means we should probably come up with self-contained representations for subscriptions and preferences that don't piggyback on top of Atom entries (but can be reasonably included as entry content for clients that, say, don't support sending media resources).
XHTML + microformats is an increasingly popular way to represent resources these days. It's easy to parse and generate XHTML in basically any client and server software, and the grammar is already known, so we don't have to come up with a new one and write validators for it. Microformats.org lists a number of best practices for defining microformats, including describing them with XMDP (which itself is just an XHTML microformat).
This week I checked in code that uses XHTML and custom microformats to represents subscriptions and preferences. Profiles and examples can be found at http://chandlerproject.org/Projects/CosmoMicroformats (the profile documents aren't available yet at their permanent non-wiki locations, but they will be shortly). I'd like to come up with examples that display more pleasantly in browsers, but the ones that are there now are perfectly useful. This is my first attempt at defining microformats, and I can't claim any mastery of semantic HTML, so it may well be that there are better element choices than span and div. Feedback is welcome.
