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>

Looking good.
I'm not sure why recent-entries should be treated as a special kind of query, it seems like building in a limitation. Will we also need a last-weeks-entries element, for instance?

The modified entry list looks an improvement, but if you're talking about resources and their description, surely this could be modified a little so that it's also valid RDF.

Nice to see the introspection example is now valid RDF, btw.

Personally I'm not sure about the hint - it seems to me that decisions about location should be entirely down to the server, and if it goes in as a hint, it's only a matter of time before people build systems that rely on it.

Posted by Danny on 2003-10-24

Danny,
  Recent-entries is just a list of entries in reverse chronological order, so if you want to go back further in time you request more entries. What I am trying to get to is the simplest thing that could work for clients and not be too much of a burden for servers to implement.

  So what are the 'little' changes I can make to the entry list to make it valid RDF?

  The problem is that there are systems  such as Bloxsom that need the location to be specified. Any suggestions on where else that information could go?

Posted by Joe on 2003-10-24

I'm quite concerned that the content and structure of the recent-entries and browse-entries data is so vaguely defined and explicitly left up to the server. This makes life difficult for a client app that wants to download a blog to local storage and allow the user to view and edit it. Such a client will want to give the user a lot of control over how to view data.

By contrast, the browse-entries format is about giving the server control, which means that a client app isn't sure what it's going to get. It really just wants a no-nonsense list of entries with all available metadata that it can use to populate its local database and UI. The more the server tries to get clever about what information to show and how to organize it, the more likely that the client app is going to have trouble extracting what it needs.

This also goes for the completely vague "description" field in the recent-entries results. A client app isn't going to know what to do with this. I guess the best guess is to shove it into the subject field of the incomplete entry; but that leads to the prospect that, after the user decides to view the entry and the client downloads its entire data, the subject will change suddenly. This doesn't make a lot of sense to the user.

IMHO Atom should just expose the raw data behind the blog to an application. Server-side fanciness and formatting should be left up to the CGI code that generates the HTML.

Posted by Jens Alfke on 2003-10-27

"IMHO Atom should just expose the raw data behind the blog to an application."

We now have three suggested interfaces  for how to choose an Entry to edit: the original multi-parameter search facet, the  simplified 'recent-entries' search facet, and finally the a static page navigation (either in the RESTLog archive format I proposed or in Sam Rubys suggested navigation).

Do you have a concrete suggestion for an alternative mechanism?

Posted by Joe on 2003-10-27

My understand is that the browse-entries provides a way to navigate entries in multiple dimensions (category, timeline, etc.) which are optionally and creatively determined and supported by the server implementation. Is this understanding correct?

It also seems, however, some of us (including myself) see the need for browsing (searching/navigation) entries remotely (on the entries on server) and locally (entries that are on user's local storage) uniformly using the same set of API's. Local entries include archived entries, drafted but not yet published entries, and also entries that are created and available on the server. It is, of course, possible, but the client implementation and the server implementation could not be decoupled.

I have not thought of an concrete alternative (though still trying...)

Posted by anonymous on 2003-10-27

Posted by anonymous on 2005-03-06