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
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 xmlns="http://example.com/newformat#" > <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> </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>sad</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
<entry xmlns="http://example.com/newformat#" > <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> <content type="application/xhtml+xml" xml:lang="en-us"> <p xmlns="...">Hello, <em>weblog</em> world! 2 < 4!</p> </content> </entry>
That's all there is to it. If serves don't support the moods extension they just won't
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.