Proposed changes to draft-gregorio-07

I've been discussing search as being the most angst filled facet. After having tossed around a couple ideas, here is a concrete proposal for how to change the spec in the next revision. While I'm at it let's slip in another proposal for the 'createEntry' facet too.

First, a quick review, the Introspection file lists all the facets that an implementation of the AtomAPI implements.

   <?xml version="1.0" encoding='utf-8'?>
   <introspection xmlns="http://purl.org/atom/ns#" > 
     <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>
     <edit-template>http://example.org/reilly/templates</edit-template>
     <categories>http://example.org/reilly/categories</categories>
    </introspection>     

The 'search-entries' facet, which is described in Secion 5.5 of the draft RFC gets split into two different facets in the Introspection file. Remove <search-entries/> and add in two new elements: <recent-entries/> and <browse-entries/>.

recent-entries

The recent-entries facet allows the client to retrieve information about the last N entries to the site. This will function just like the 'search-entries' facet except that it will only accept one search parameter 'atom-last'. The 'atom-last' query parameter is set to the number of recent entries to return. It returns a file in the same format as is currently specified for the 'search-entries' facet.

For example, if the 'recent-entries' element has the URI http://example.org/recent/ for a value, then doing a GET on the URI:

http://example.org/recent/?atom-last=2

Will retrieve descriptions of the last 2 Entries. The results returned would look like:

HTTP/1.1 200 Ok 
Content-Type: application/x.atom+xml

<?xml version="1.0" encoding='utf-8'?>
<recent-entries xmlns="http://purl.org/atom/ns#" > 
  <entry>
    <title>My First Post</title>
    <id>http://example.org/reilly/1</id>
  </entry>
  <entry>
    <title>My Second Post</title>
    <id>http://example.org/reilly/2</id>
  </entry>
</recent-entries>

Now there have been questions regarding the use of id and title in the search results. The use of id isn't consistent with the use in the Atom format, or at least it could conflict with the use that the server implementation had chosen. Title is also a bit problematic in that an Entry may not have a title. Here is a proposed alternative:

HTTP/1.1 200 Ok 
Content-Type: application/x.atom+xml

<?xml version="1.0" encoding='utf-8'?>
<recent-entries xmlns="http://purl.org/atom/ns#" > 
  <resource>
    <description>My First Post</description>
    <link>http://example.org/reilly/1</link>
  </resource>
  <resource>
    <description>My Second Post</description>
    <link>http://example.org/reilly/2</link>
  </resource>

</recent-entries>

description is a string that is to be displayed to the user when choosing an Entry to edit. It should contain enough information that the user can adequately distinguish between Entries. It could contain the title of the Entry if it had one, but that is just suggested practice and the server completely determines the content of this element.

The link element contains the 'editEntry' URI for the Entry being described.

browse-entries

The browse-entries facet contains a URI of a file in 'archive' format. This is the alternate search mechanism I discussed in Reconsidering Search (Kinda) in the AtomAPI and elaborated on further in a message to the atom-syntax mailing list.

Both the 'recent-entries' facet and the 'browse-entries' facet are optional. This lets the implementation choose which, if any, searching mechanism works best.

Hinting at a location

The last proposed change is for the 'create-entry' facet. In this case I propose that the <link> element of the POSTed Entry can optionally be filled in with a relative URI path. The value of the <link> element can serve as a hint to the server on what URI to assign the Entry. This could be used by Blosxom to determine the directory to place the entry. The link element is optional and the server may ignore its value when processing a POST to create a new Entry. Here is an example of a POST to create an Entry with the link tag filled in:

POST /some-atom-cgi-handler.cgi HTTP/1.1
Content-Type: application/x.atom+xml

<entry>
    <link>/tech/pantherUpgrade.html</link>
    <title>Mac OS: less crap</title>
    <content type="application/xhtml+xml" mode="xml">
        <div xmlns="http://www.w3.org/1999/xhtml">
           The NYT has a glowing
           article about the Panther upgrade to Mac OS X...
        </div>
    </content>
    <issued>2003-10-23T08:17:00-04:00</issued>
    <modified>2003-10-23T08:17:00-04:00</modified>
</entry>