Extending the AtomAPI

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>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 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.