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/>.
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
for a value, then doing a GET on the URI:
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
title in the search results. The use of
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.
is also a bit problematic in that an Entry may not have a title. Here is a
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
link element contains the 'editEntry' URI for the
Entry being described.
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>