General

The browser will poll the client for results to display. It is up to the browser how frequent this polling occurs (it might even be user initiated).

The initial polling will be done by a normal HTTP request, where the search query is encoded in the url. The resulting page will define a search key, that can be used to retrieve results.

A search will be initiated with a query of the form:

http://localhost/startsearch?query=xyz&timeout=seconds&...

Where xyz is a urlencoded string, and seconds is the number of seconds this query should be running (=listening for results from network). - generic arguments depending on cgi-plugin used.

The result will be a SearchInitiatedResponse.

Retrieving results will be done with a query of the form:

http://localhost/getresults?key=12345&limit=3

Note: this is by no means an exhaustive specification, for that a DTD will be generated. This is the initial proposal, up for discussion.

ErrorResponse

<response id="ErrorResponse">
<msg code="1234">Something went wrong</msg>
</response>

SearchInitiatedResponse

<response id="SearchInitiatedResponse">
<key>12345</key>
</response>

Here, 12345 is the key returned by oscar to indicate the unique search identifier assigned to this search request. This can be any character string consisting of at most 127 alphanumeric characters.

SearchResultResponse

<response id="SearchResultResponse">
  <result id="result00">
     <title value="dskjfs" />
     <link>bla</link>
     <description/>
     <date/>
     <tags/>
  </result>
  <result id="result01">
    ..
  </result>
  ..
</response>

A SearchResultResponse may contain any number of <result> blocks, depending on the show parameter of the query. If no show parameter is present, the default is to put 10 results on a page.

A <result> block will always contain a non empty title and url. Description, date and tags are optional. The date should be a unix timestamp (timezone?) and should be the date of last retrieval. The tags can be user specified or index keywords.

The SearchResultResponse? information is a subset of the opensearch result set, which will be used internally in the open-search-client.