The Atom Publishing Protocol

Joe Gregorio

BitWorking, Inc

The Structure of the Presentation

• History of blogging APIs
• Basic operation of the Atom Publishing Protocol
• Applications to areas outside weblogs

Why Blogging APIs?

?

• Allow the publishing to be decoupled from the HTML interface.
• Allow the use of 'Rich Clients' for publishing.

History of Blogging APIs

LiveJournal

• One of the earliest weblog updating protocols.
• Uses 'application/x-www-form-urlencoded' encoded data sent to the server.
• The response is encoded as a series of key/value pairs separated by newlines.
• Called The LiveJournal Flat Client/Server Protocol

LiveJournal (Example Request)

POST /interface/flat HTTP/1.0
Host: www.livejournal.com
Content-type: application/x-www-form-urlencoded
Content-length: 34

mode=login&user=test&password=test

LiveJournal (Example Response)

HTTP/1.1 200 OK
Date: Sat, 23 Oct 1999 21:32:35 GMT
Server: Apache/1.3.4 (Unix)
Connection: close
Content-Type: text/plain

name
Mr. Test Account
success
OK
message
Hello Test Account!

LiveJournal Capabilities

• Create a new log entry.
• Edit/Delete an existing log entry.
• Get a list of log entries.

There are other capabilities relating to 'friend' management.

LiveJournal

While not a major protocol today it set the pattern for many of the publishing APIs that would follow.

• Everything is done through HTTP POST
• Everything goes through one URI
• Does not use HTTP Authentication

LiveJournal - Everything in POST

• Beyond POST there are other HTTP methods to choose from:
• GET - The GET method means retrieve whatever information (in the form of an entity) is identified by the Request-URI.
• PUT - The PUT method requests that the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server.
• DELETE - The DELETE method requests that the origin server delete the resource identified by the Request-URI.

XML-RPC

• The ink had barely dried on the XML specification (Feb-1998) when Dave Winer introduced (Mar-1998) XML-RPC.
• Remote Procedure Call
• Uses XML over HTTP.
• The name of the function to call and the arguments to that function are packed into XML and put into the HTTP request. The response contains an XML entity with the results of that function call.

XML-RPC Example Request

POST /RPC2 HTTP/1.0
User-Agent: Frontier/5.1.2 (WinNT)
Host: betty.userland.com
Content-Type: text/xml
Content-length: 181

<?xml version="1.0"?> 
<methodCall> 
   <methodName>examples.getStateName</methodName> 
   <params> 
      <param> 
        <value>
          <i4>41</i4>
       </value> 
     </param> 
   </params> 
</methodCall> 

XML-RPC Request Body

<?xml version="1.0"?> 
<methodCall> 
   <methodName>examples.getStateName</methodName> 
   <params> 
      <param> 
        <value>
          <i4>41</i4>
       </value> 
     </param> 
   </params> 
</methodCall> 

• Note that this isn't really a 'document' so much as a serialization of function call parameters.
• Also note that lack of namespaces.

XML-RPC

XML-RPC follows the same patterns that the LiveJournal API set.

• Everything is done through HTTP POST
• Everything goes through one URI
• Does not use HTTP Authentication

In addition, for most of the life of the XML-RPC specification, the content of 'string' parameters transported via XML-RPC were restricted to ASCII.

XML-RPC Protocols

Despite those weaknesses several popular APIs were built on ..

API is the wrong term.

• API is the wrong word.
• Interface is ok.
• Protocol is the proper word.
• I'm guilty of this as much as anyone, the early versions of the Atom Publishing Protocol were initially called the AtomAPI.

XML-RPC Based Protocols

• Despite the weaknesses, and the fact that API is the wrong name, several popular APIs were built on XML-RPC
• The Manilla-RPC Interface
• The Blogger API
• The MetaWeblog API
• The LiveJournal XML-RPC Client/Server Protocol

XML-RPC Based Protocols Evolution

XML-RPC Based Protocol Weaknesses

Because they were built on top of XML-RPC, and because of design decisions in the protocols themselves, there are some weaknesses with all of the protocols listed.

Weakness - I18N

• Internationalization is a problem since XML-RPC limited string parameters to ASCII.

Weakness - Extensibility

• XML-RPC based protocols aren't easily extensible.
• No understanding of XML namespaces.

Weakness - Authentication

• None use the built-in authentication of HTTP.
• Many send passwords as clear text.

Weakness - Features

• One of the protocols doesn't allow you to set dates or titles of published entries.

Weakness - Poor utilization of HTTP

• Everything is done via POST
• Everything is done through the same URI
• This means that if you were trying to build a large system to handle many such requests and wanted to dispatch different requests to different servers you would have to parse the XML body before knowing where to dispatch it to. Obviously a solution that provided information in the headers, such as the URI, the method and the content-type would be much faster to pull out and dispatch on than parsing an XML document.

Weaknesses - Summary

• So these protocols take XML and try to use it in a way that removes two of the most important qualities that XML brings to the table; I18N and extensibility.
• In addition they use HTTP but ignore the built in authentication mechanism and the ability of servers to quickly dispatch requests based on the headers of a request and not just the contents.

Enter the Atom Publishing Protocol

• So what is the Atom Publishing Protocol, how does it work, and how does it address the problems of the XML-RPC based protocols?

Enter the Atom Publishing Protocol

• Before we take the plunge into the Atom Publishing Protocol we'll need to take a little diversion and talk about all the facets of Atom:
  • Atom the IETF Working Group
  • Atom the Syndication Format
  • Atom the Publishing Protocol

Atom the IETF Working Group

• Officially known as "Atom Publishing Format and Protocol (atompub)"
• From the charter:
  • Atom defines a feed format for representing and a protocol for editing Web resources such as Weblogs, online journals, Wikis, and similar content.
  • The feed format enables syndication; that is, provision of a channel of information by representing multiple resources in a single document.
  • The editing protocol enables agents to interact with resources by nominating a way of using existing Web standards in a pattern.

Origins

• Sam Ruby's wiki that launched much of this work was opened for business on June 16, 2003.
• Pre-IETF work was done on the [atom-syntax] mailing list graciously hosted by imc.org starting in July 2003.
• The Atompub WG was started in June 2004 and resides on the [atom-syntax] mailing list. The wiki is still used heavily though the nature of that use has changed over time.

Status

• Currently several Internet-Drafts, no RFCs.
• Goals
• Mar 05 Request Last Call for Atom editing protocol
• Apr 05 Submit Atom editing protocol to IESG for consideration as a Proposed Standard

Protocol Charter

• The editing protocol must enable:
• Creating, editing, and deleting feed entries
• Multiple authors for a feed
• Multiple subjects or categories in a feed
• User authentication
• Adding, editing, and deleting users
• Setting and getting user preferences
• Creating, getting and setting related resources such as comments, templates, etc.

Workgroup Products

• The output of the WG is both a syndication format and a publishing protocol.
• One of the key aspects of the protocol is to leverage as much of the syndication format as possible.
• So, one of the first steps to understanding the publishing protocol is to understand the syndication format.

Atom Syndication Format Example

<?xml version="1.0" encoding="utf-8"?>
<feed version="NNN"
    xmlns="http://purl.org/...">
     <head>
       <title>Example Feed</title>
       <link href="http://example.org/"/>
       <updated>2003-12-13T18:30:02Z</updated>
       <author>
         <name>John Doe</name>
       </author>
     </head>
     <entry>
       <title>A Simple Title</title>
       <link href="http://example.org/2003/12/13/atom03"/>
       <id>vemmi://example.org/2003/32397</id>
       <updated>2003-12-13T18:30:02Z</updated>
       <content>This is the content of the entry. Lorem Ipsum Dolor...</content>
     </entry>
</feed>

Atom Syndication Format Highlights

• Namespaces!
• Titles
• Entries are the things were most interested in, they're what we are going to be spending the most time dealing with in the protocol.

Let's look closer at an 'entry'

<entry xml:ns="http://purl.org/...">
  <title>A Simple Title</title>
  <link href="http://example.org/2003/12/13/atom03"/>
 
  <author>
    <name>Marge Inoverrah</name>
  </author>

  <id>http://example.org/2003/32397</id>
  <updated>2003-12-13T18:30:02Z</updated>

  <published>2003-12-13T18:30:02Z</published>
	   
  <summary type="TEXT">The history and lore of Lorem Ipsum.</summary>

  <content type="TEXT">Lorem Ipsum Dolor...</content>
</entry>

The Entry

• Contains the basic information needed for an entry.
• The 'entry' is the cornerstone of the Atom Publishing Protocol.
• Note how we are setting up a base for a 'Document Literal' approach vs the XML-RPC approach of serialized function parameters.

Common actions in the Atom Publishing Protocol

• Keep the focus to the same parts of the protocols we've reviewed so far:
• Create a new entry
• Edit/Delete an entry
• Get a list of entries.
• In the RPC world these were just different procedure calls.

Resources

• Now we get to address that first major weakness of the RPC protocols and give all the appropriate pieces their own URIs.
• That is, entries and collections of entries become first class web citizens.

Edit

• So how do you edit an entry via Atom?
• Each entry has it's own URI
• So do a GET on that URI.

GET

• What a novel concept, GET!
• Only 99.9% of the traffic on the web is in the form of GETs.
• Do you think the web might be optimized to handle GETs?

Get a list of entries.

• So how do you get a list of entries via Atom?
• Each Entry Collection has it's own URI
• So do a GET on that URI.

Did I mention GET?

• What a novel concept, GET!
• Only 99.9% of the traffic on the web is in the form of GETs.
• Do you think the web might be optimized to handle GETs?

Delete

• So how do you delete an entry via Atom?
• Each entry has it's own URI
• So do a DELETE on that URI.
• You knew all those methods would come in handy.

Common actions in the Atom Publishing Protocol - Update

• So how do you update an entry via Atom?
• Each entry has it's own URI
• So do a PUT of the updated entry to that URI.

Common actions in the Atom Publishing Protocol - Create

• So how do you create an entry via Atom?
• POST the entry to the URI of the Entry Collection.
• From the HTTP spec (RFC 2616):

  POST is designed to allow a uniform method to cover the following functions: ... Posting a message to a bulletin board, newsgroup, mailing list, or similar group of articles;

Create Info Graphic

Atom Publishing Protocol Summary

Examples

• Assume our Entry Collection lives at http://example.com/reilly.
• Assume each Entry lives at http://example.com/reilly/N

Note: URIs are opaque in Atom.

Example - Get the Collection

• We are given the URI of an Entry Collection (Don't worry about how we got that URI to begin with.)
• Doing a GET on that URI returns part of the Collection.
• Note it is formatted as an Atom Feed.

Example - Get Collection - Request

GET /reilly/ HTTP/1.1
Host: example.org
Content-Type: application/atom+xml

Example - Get Collection - Response

HTTP/1.1 200 Ok
Content-Type: application/atom+xml
Content-Length: nnnn 

<?xml version="1.0" encoding="utf-8"?>
<feed version="NNN"
    xmlns="http://purl.org/...">
     <head>
       <title>Example Feed</title>
       <post href="http://example.org/reilly/"/>
       ...
     </head>
     <entry>
       <title>A Simple Title</title>
       <edit href="http://example.org/reilly/3"/>
       <content>This is the content of the entry. Lorem Ipsum Dolor...</content>
     </entry>
     ...
     <entry>
       <title>Another Simple Title</title>
       <edit href="http://example.org/reilly/1"/>
       <content>More content.</content>
     </entry>
</feed>

Example - Get Collection - Response

• Note the post and edit elements.

Example - Create a new Entry

• POST to the same URI, the one for the Entry Collection.
• We are POSTing an Atom Entry.

Example - Create a new Entry - Request

POST /reilly HTTP/1.1
Host: example.org
Content-Type: application/atom+xml

<?xml version="1.0" encoding='utf-8'?>
<entry 
  xmlns="http://purl.org..." >  
  <title>My First Entry</title> 
  <summary>A very boring entry...</summary> 

  <author> 
    <name>Bob B. Bobbington</name> 
  </author> 

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

  <content type="XHTML" xml:lang="en-us"> 
    <p xmlns="...">Hello, <em>weblog</em> world!</p> 
  </content>  
</entry> 

Example - Create a new Entry - Response

HTTP/1.1 201 Created
Location: http://example.org/reilly/4

Example - Deleting an entry

• DELETE on the URI returned in the Location: header.

Example - Delete - Request

DELETE /reilly/4 HTTP/1.1
Host: example.org