Re: ATOM representation of search result facets

tl;dr: Use OpenSearch.

On Tue, Aug 28, 2012 at 11:35 PM, Rich Cariens <[email protected]>wrote:

>  I need to start including facet counts in my ATOM search results. I'd
> prefer to reuse existing ATOM elements and attributes if possible.
>

As others have said, there are no built-in atom constructs for the things
you seek other than e.g. putting the facet counts in parenthesis in the
title attribute; your users will quickly understand that "35mm Canon (134)"
means that there are 134 hits for 35mm Canon.

<link rel="related" title="35mm Canon (134)"  ...  />

When it comes to machine consumption, this won't cut it.  There are,
however a range of extensions to atom that fit what you want to do.

To identify the number of items in a link, there's the "threading"
extension [1] which defines the "thr:count" attribute.  It defines the
number of items behind a link.  The threading extension does talk about
atom collections of comments, and the RFC does limit the specification of
the thr:count to be used on link relations of type "replies"... But IMHO
the extension is more widely applicable to count "the number of items in a
feed behind a <link>."

<link rel="related" title="Canon (134)" thr:count="134" ...  />

This might not float your boat, so the second thing I would like to point
you to is OpenSearch [2], a wonderful media type and XML language, suitable
for embedding in atom feeds, especially search results.

The full use case for OpenSearch is to inform clients that "here's a search
engine!" and to educate the client on *how* to use it, e.g. to have
browsers discover and use search engines with no user intervention.  The
browser discovers an OpenSearch description document in the web pages, and
then provide search facilities for that server in their search bars.  This
in itself is extremely useful in M2M scenarios where a link relation
"search" which provides an OpenSearch description document allows machines
to perform searches.  Powerful stuff.

OpenSearch provides a number of useful elements to be able to drill down
into responses too, indeed, supporting faceting too, e.g. the Query element
[3].

   <opensearch:Query role="subset"
        searchTerms="35mm Manufacturer:Canon"
        totalResults="134"
        title="Canon" />

This would be enough to tell an OpenSearch aware atom processing client
that if the searchTerms is set to "35mm Manufacturer:Canon" that a subset
will be made available with 134 items, and to use the label "Canon" when
showing this to a user.

The Query object is usually present in an atom feed when there is a link to
an OpenSearch description document, and usually the same description
document that was used to make the query.  I believe that the Query
(together with the description document) constitutes a link, even though
there is no explicit href anywhere.  The <Uri> element of the description
document contains a primitive form of an URI template, and the attributes
of the Query element are used to fill out the values of the URI template.

So, given an OpenSearch description document with the following template:

<Url type="application/atom+xml"
     template="/search?q={searchTerms}" />

... and the following element in the atom feed available at /search?q=35mm
(of course with a link back to the OpenSearch description document):

<opensearch:Query role="subset"
      searchTerms="35mm Manufacturer:Canon"
      totalResults="134"
      title="Canon" />

... then the client will be able to construct the URI
"/search?q=35mm%20Manufacturer%3ACanon", in the expectation of finding a
subset of items from the original query, somehow connected to the text
"Canon" (the title).

What we're missing is of course for OpenSearch to go through the hoops of
being an IETF standard and an IANA registered media type. DeWitt Clinton?

It's not interesting to ask if it is more or less RESTful to do things
using OpenSearch.  I feel it's a way of decoupling the server and the
client; the server may or may not include <Query> elements, and the clients
may or may not understand them if they do, and don't break if they're not
there.  It caters for evolvability in both, and that's a big benefit.

As you might understand, I believe OpenSearch to be quite underrated :-)

On a related note, a friend and colleague (Erlend Hamnaberg) invited me to
help him work on an OpenSearch extension to be able to express more
advanced filtering capabilities [4] in OpenSearch responses atom feeds.
 It's in a very early draft stage :-)

There are many other draft OpenSearch extensions too, e.g. for querying
based on date/time values [5], or by geospatial values [6].

[1]: http://tools.ietf.org/html/rfc4685
[2]: http://www.opensearch.org/
[3]:
http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_Query_element
[4]:
https://github.com/hamnis/opensearch-filter/blob/master/filter/middle.mkd
[5]:
http://www.opensearch.org/Specifications/OpenSearch/Extensions/Time/1.0/Draft_1
[6]:
http://www.opensearch.org/Specifications/OpenSearch/Extensions/Geo/1.0/Draft_2
-- 
-mogsie-