XML.com: XML From the Inside Out
oreilly.comSafari Bookshelf.Conferences.

advertisement

The Atom API
by Mark Pilgrim | Pages: 1, 2

API Discovery

Previous weblog services had no concept of API discovery. They left it up to the end user to provide the exact API URL (http://example.com/mt/mt-xmlrpc.cgi). Some servers implemented undocumented functions like deletePost, and even knowing the type of software running on the other end was not enough because different versions of the same software supported extra functionality over time. Client software had to guess what functionality was provided and what extensions were supported

The Atom API assumes only that the end user knows her home page. It relies on a link tag in the head element of the home page that points to an Atom introspection file. The introspection file, in turn, lists the supported functions and extensions, as well as the URI associated with each function.

Here is an example of a home page with Atom API auto-discovery:


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>My Weblog</title>
<link rel="service.edit" type="application/x.atom+xml" 
  href="/myblog/atom.cgi/introspection" title="Atom API" />
</head>
<body>
...
</body>
</html>

If this resource is http://www.example.com/, it says that the Atom introspection file is the http://www.example.com/myblog/atom.cgi/introspection resource. Note that this is actually routing through a CGI script, as are all the other examples I'll list here. Nothing in Atom requires this, but when I wrote a server prototype of the Atom API, I made a point to route everything through a single CGI script because there was some debate about whether this was even possible. It could easily be a set of CGI scripts, or JSPs, ASP, PHP, or any other language.

The introspection file then lists the supported function and extensions in a simple, well-defined XML format. There are a number of functions defined in the core Atom API, and vendors can extend the introspection file with XML namespaces to point to their own extension methods. A core Atom API introspection file (like http://www.example.com/myblog/atom.cgi/introspection) might look like this:

GET /myblog/atom.cgi/introspection HTTP/1.1
Host: example.com
HTTP/1.1 200 OK
Content-Type: application/x.atom+xml

<?xml version="1.0" encoding="utf-8"?>
<introspection xmlns="http://purl.org/atom/ns#" > 
  <search-entries>http://example.com/myblog/atom.cgi/search</search-entries>
  <create-entry>http://example.com/myblog/atom.cgi/edit</create-entry>
  <edit-template>http://example.com/atom.cgi/templates</edit-template>
  <user-prefs>http://example.com/myblog/atom.cgi/prefs</user-prefs>
  <categories>http://example.com/atom.cgi/categories</categories>
</introspection>

Retrieving Entries

If you're writing client software to manage a weblog, the first thing you'll probably want to do after getting the introspection file is get a list of existing entries. The introspection file lists the address for searching entries in <search-entries>. The client can add query string parameters such as atom-last to find recent entries. More complex examples are defined in the Atom API spec draft.

Here's how you would get a list of recent entries:

GET /myblog/atom.cgi/search?atom-last=20 HTTP/1.1
Host: example.com
HTTP/1.1 200 OK
Content-Type: application/x.atom+xml

<search-results xmlns="http://purl.org/atom/ns#" > 
  <entry>
    <title>My Second Post</title>
    <id>http://example.com/atom.cgi/edit/2</id>
  </entry>
  <entry>
    <title>My First Post</title>
    <id>http://example.com/atom.cgi/edit/1</id>
  </entry>
</search-results>

The remainder of the Atom API follows the principles of REST. New entries are created using HTTP POST to post an Atom entry to the create-entry address specified in the introspection file. Retrieving an entry is accomplished by doing an HTTP GET on the entry's URI, which is returned after creating new entry or in search results. Editing an entry is accomplished by doing an HTTP PUT on the entry's URI; deleting an entry is an HTTP DELETE on the entry's URI.

When I say "the entry's URI", remember that that's implementation-specific. These examples route everything through a single script (atom.cgi), just to prove that you can do that. Of course if you're implementing the Atom API on your own server, you don't have to do that; you could use JSP, or PHP, or Perl, or anything that can handle the four basic HTTP operations (GET, POST, PUT, DELETE). The introspection file rules all; it's the client's guide to the structure of the server's Atom web services.

As I said, retrieving an existing entry is as simple as an HTTP GET of the entry's URI. The search results told us that the first post had a URI of http://example.com/atom.cgi/edit/1, so let's get that:

GET /myblog/atom.cgi/edit/1 HTTP/1.1
Host: example.com
HTTP/1.1 200 OK
Content-Type: application/x.atom+xml

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://purl.org/atom/ns#">
  <title>My First Entry</title> 
  <summary>My First Entry Excerpt (generally plaintext)</summary> 
  <author> 
    <name>Bob B. Bobbington</name> 
    <email>bob@example.com</email>
    <url>http://homepage.example.com/</url>
  </author> 
  <issued>2003-10-15T02:29:29</issued> 
  <created>2003-10-15T04:10:58Z</created> 
  <modified>2003-10-15T04:22:03Z</modified> 
  <link>http://example.com/myblog/archives/2003/11/19/My_First_Entry.html</link>
  <id>urn:example-com:myblog:1</id>
  <content type="application/xhtml+xml" xml:lang="en"> 
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p>Hello, <em>weblog</em> world!</p>
      <p>This is my first post <strong>ever</strong>!</p>
    </div>
    </content>  
</entry>

Lots of information here: the entry has a title, an excerpt or summary, and an author who has a name, email address, and URL of his own. The entry has a created date and a modified date (usually server-generated), and an "issued" date (which is a date that the author would like to give to this entry, separate from when he actually posted it). The entry is viewable at a specific link, has an internal ID (a URN), and finally has some XHTML content.

The Atom content model is probably worth a whole article by itself, but for the moment let me just handwave and say that it can handle more than just XHTML. Any MIME type can be expressed (specify it in the @type attribute), and non-XML content (such as HTML or plain text) is simply escaped or put in a CDATA block, with a mode="escaped" attribute on the content element. It can even handle binary content (such as an image) by specifying @mode="base64" and including a base64-encoded representation of the data.

Creating, Editing, and Deleting entries

Posting a new entry is virtually symmetrical. To create a new entry, do an HTTP POST on the URI create-entries address specified in the introspection file. The body of the HTTP POST should be an entry, in the same Atom format as you got back from the server on retrieve:

POST /myblog/atom.cgi/edit HTTP/1.1
Host: example.com
Content-Type: application/x.atom+xml

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://purl.org/atom/ns#">
  <title>My Entry Title</title> 
  <created>2003-11-17T12:29:29Z</created> 
  <content type="application/xhtml+xml" xml:lang="en"> 
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p>Hello, <em>weblog</em> world!</p>
      <p>This is my third post <strong>ever</strong>!</p>
    </div>
  </content>  
</entry>

The server responds with an HTTP status code 201 "Created" and gives the entry's edit URI in the HTTP Location: header.

HTTP/1.1 201 Created
Location: http://example.com/myblog/atom.cgi/edit/3

Note that since we're using straight XML (rather than a serialization of XML over RPC over XML), extensibility is handled by XML namespaces. For example, Movable Type allows individual entries to allow comments or not. This functionality is not built into the Atom API, but Six Apart could easily extend the API like this:

POST /myblog/atom.cgi HTTP/1.1
Host: example.com
Content-Type: application/x.atom+xml

<?xml version="1.0" encoding="utf-8"?>
<entry
  xmlns="http://purl.org/atom/ns#"
  xmlns:mt="http://www.movabletype.org/atom/ns#">

  <title>My Entry Title</title> 
  <created>2003-11-17T12:29:29Z</created>
  <mt:allowComments>1</mt:allowComments>
  <content type="application/xhtml+xml" xml:lang="en"> 
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p>Hello, <em>weblog</em> world!</p>
      <p>This is my first post <strong>ever</strong>!</p>
    </div>
  </content>  
</entry>

Modifying an existing entry is almost the same as creating one. You do an HTTP PUT on the entry's URI (as returned in the Location: header after creating it or in the id element in the search results), with the entry in the body of the HTTP message, in the same Atom XML format we've seen in other method calls:

PUT /myblog/atom.cgi/edit/1 HTTP/1.1
Host: example.com
Content-Type: application/x.atom+xml

<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://purl.org/atom/ns#">
  <title>My First Entry</title> 
  <summary>My First Entry Excerpt (generally plaintext)</summary> 
  <author> 
    <name>Bob B. Bobbington</name> 
    <email>bob@example.com</email>
    <url>http://homepage.example.com/</url>
  </author> 
  <issued>2003-10-15T02:29:29</issued> 
  <created>2003-10-15T04:10:58Z</created> 
  <modified>2003-10-15T04:22:03Z</modified> 
  <link>http://example.com/myblog/archives/2003/11/19/My_First_Entry.html</link>
  <id>urn:example-com:myblog:1</id>
  <content type="application/xhtml+xml" xml:lang="en"> 
    <div xmlns="http://www.w3.org/1999/xhtml">
      <p>Hello, <em>weblog</em> world!</p>
      <p>This is my first post <strong>ever</strong>!</p>
    </div>
    </content>  
</entry>

On success the server responds with an HTTP status code 205 "Reset Content".

HTTP/1.1 205 Reset Content

Deleting an entry is even simpler:

DELETE /myblog/atom.cgi/edit/3 HTTP/1.1
Host: example.com
HTTP/1.1 200 OK

Further reading

More Dive Into XML Columns

Identifying Atom

XML on the Web Has Failed

The Atom Link Model

Normalizing Syndicated Feed Content

Atom Authentication

We have, in some sense, come full circle. The original LiveJournal API was REST-based, although it was limited to the simple name-value pairs for input and output. After that, weblogging APIs went down a path of RPC-style services, until that became completely unmanageable. And now we're back to a document-centric, REST-inspired service again.

The Atom API has several other methods beyond add, edit, delete, retrieve, search. It can be used for posting comments on entries, managing users and user preferences, managing categories, managing site templates; eventually it will be usable for everything you can do manually with your weblog through your server's browser-based interface. You can read the latest draft for yourself or download sample source code that implements the API in Python, Perl, PHP, or Java.

"But, but, but," I hear you cry, "what about passwords sent in the clear?" Ah, yes. Atom authentication deserves its own article, and I promise to tackle it, if not next month then the month after. I can promise that it does not involve sending plain text passwords in the clear.



1 to 5 of 5
  1. SOAP?
    2003-10-17 22:54:24 Terris Linenbach
  2. Finally, it's clear why we have Atom
    2003-10-16 19:55:05 Steve Kirks
  3. Informative, But...
    2003-10-16 10:40:17 Don Park
  4. Clarification of resources
    2003-10-16 09:13:02 David Czarnecki
  5. ManilaRPC
    2003-10-15 18:48:42 Dave Winer
1 to 5 of 5