One of the key features of the AtomAPI is it's potential for extensibity. As an example of that kind of extensiblity here in an outline of one way the AtomAPI could be enhanced in a completely safe way by a vendor. The example I am going to use is that of moods.

Moods are pretty particular to LiveJournal and are reflected in their current XML-RPC interface. A mood is just that, the mood of the writer at the time they wrote their entry.

The first thing we do is assign a namespace. Since this is an extension and not part of the core API the elements we add must appear in a namespace different from that of the core elements. In this case I'll choose some.lj.example.com/namespace/, which is just an example. It's not normative. Don't really use it. Nor is the rest of this article in anyway normative, or a real specification, it is just a theoretical example. Have I stressed that point sufficiently? Good.

Now the first two questions to answer are, how do we know if a particular AtomAPI implementation supports moods, and if so, what are the allowable moods, that is, how does the client retrieve a list of moods the user can choose from?

The answer to both questions is an extension to the Introspection file. In this case, adding a new element, in the LJ namespace, called lj:moods, signals that the API understand the mood facet. Further, if you do a GET on that URI given in the lj:moods element you will retrieve a list of allowable moods. So here is our enhanced Introspection file:

<introspection
xmlns="http://example.com/newformat#"
xmlns:lj="some.lj.example.com/namespace/" >
<create-entry>http://example.org/reilly/</create-entry>
<user-prefs>http://example.org/reilly/prefs</user-prefs>
<search-entries>http://example.org/reilly/search</search-entries>
<lj:moods>http://example.org/reilly/moods</lj:moods>
</introspection>  

And here is an example moods file returned by doing a get on the lj:moods URI.

<moods xmlns="some.lj.example.com/namespace/" >
<mood>happy</mood>
<mood>angry</mood>
</moods>

Now the client knows this server supports the mood facet and also has the list of moods to present to the user. The last part is actually incorporate the mood in to the Entry. This is again done by adding a namespaced element, this time when creating a new entry. Note that the same holds for PUTing an Entry to update it. So if we create a new Entry while angry, then this is what would be POSTed to the create-entry URI.

<entry
xmlns="http://example.com/newformat#"
xmlns:lj="some.lj.example.com/namespace/" >
<title>My First Entry</title>
<subtitle>In which a newbie learns to blog...</subtitle>
<summary>A very boring entry...</summary>

<author>
<name>Bob B. Bobbington</name>
<homepage>http://bob.name/</homepage>
<weblog>http://bob.blog/</weblog>
</author>

<issued>2003-02-05T12:29:29</issued>

<lj:mood>happy</lj:mood>

<content type="application/xhtml+xml" xml:lang="en-us">
<p xmlns="...">Hello, <em>weblog</em> world! 2 &lt; 4!</p>
</content>

</entry>


That's all there is to it. If serves don't support the moods extension they just won't add an lj:moods element to their introspection file. If clients don't support the moods extension they'll never go looking for the lj:moods element. In either case, both client and server are robust to the extension and keep on working with or without the new behaviour.

Awesome example.
If we ever name this beast it will rock.

Posted by Nick Chalko on 2003-08-06

May I compound the problem? Let's say that LJ allowed users to have multiple moods per post and that each mood could have several attributes, not just one.

I'm really thinking of the case where I have a more complex form to fill out.

Posted by Phil Wolff on 2003-08-08

LJ supports reader access controls at the post level. So you have to specify an ACL when you post, and identify yourself when you read.

This means that when I'm composing a post for LJ, I want to (a) authenticate myself, (b) pull down a list of my defined friends and buddy lists, (c) attach intended readership (private, named people, named lists, or public) to each post I write. When consuming a feed, I need to provide sufficient ID information that the Atom server filters the content that I'm intended to see.

Are namespaces enough? Or are there specific API behaviors not currently defined?

Other blog hosts have similar requirements (Xanga, for example) and enterprise systems will definitely demand them.

Posted by Phil Wolff on 2003-12-05