++++++++++++++++++++
The Search Interface
++++++++++++++++++++
------------------------
The search on properties
------------------------

:Author: Guido Goldstein
:Email: gst@infrae.com
:License: BSD, see LICENSE.txt


1. The public search interface
==============================

Like all other functionalities of the Railroad system, the search is
available through a URL. There is one URL in the search service of Railroad
that accepts generic queries on properties (suprisingly called generic
search) and a bunch of URLs that do much more specialised searches.


2. Genric Queries
=================

2.1 Syntax
----------

tbd


2.2 Result format
-----------------

tbd


3. Specialized Queries
======================

3.1 Find unowned resources
--------------------------

3.1.1 The Request
_________________

This search request will find all resources that are currently not
owned by others. The ownership is determined by the database.

This functionality is a core service which can be reached under:
 /service/find-unowned

The following parameters will be supported in the future:

**1. start-date**

  Will limit the resources returned to those newer than the given date
  and time. The value of the parameter has to be an ISO timestamp.

**2. end-date**

  Will limit the resources returned to those older than the given date
  and time. The value of the parameter has to be an ISO timestamp.

**3. mime-type**

  One or more (comma separated) mime/types. Only resources where the
  'getcontenttype' properety matches one of the given mime-types are
  returned.


The request does not provide a method of ``batching`` the result
because this would imply a stateful connection/request handling or
execution of the same query multiple times. I consider both a waste of
resources, so the request will always return the complete result-set.


3.1.2 The Response
__________________

The response type is always text/xml.

Response to the find-unowned request is -- in general -- a collection
of entries which briefly describe a existing resource. Most of the
WebDAV properties are not included in the response because this
would cause large responses (and the additional data is not needed
in most cases).


3.1.3 XML Format
________________

Below a brief description of the XML structure returned by the
find-unowned request.

::

  <?xml version="1.0" encoding="utf-8"?>
  <search-response xmlns="http://www.infrae.com/namespaces/railroad/search/find-unowned"
    <request>http://nova.infrae:82/service/find-unowned</request>
    <result-size>100</size>
    <resources>
      <resource>
        <url>http://nova.infrae:82/rrr/repo/image/jpeg/000/8892-1.jpg</url>
        <mime-type>image/jpeg</mime-type>
        <size>35342</size>
        <lastmodified>2005-02-03T13:24:41Z</lastmodified>
      </resource>
      .
      .
      .
    </resources>
  </search-response>


The response is always encoded in utf-8 to ensure support for resource names
containing non-ascii characters.



..
   Local Variables:
   mode: rst
   indent-tabs-mode: nil
   sentence-end-double-space: nil
   fill-column: 70
   End:
