Version 1.1, 12th January 2004

Introduction

SRU is a simple HTTP GET form of the service. The request is encoded within the URL, much like OpenURL, as opposed to in an XML document which is sent to the server.

The response, on the other hand, uses the same schema as the base SOAP response, but without the SOAP Envelope wrapper. Additionally the SRU response may not include full type information on the elements and may include two extra elements, defined below.

URL Syntax

The parameters from the service description are the names of the fields within the URL. Special characters such as " [ ] or & and so forth are not valid within URLs so must be escaped if present within any of the parameters.

Operations

In SRW, the operation is determined by the SOAPAction HTTP header and the name of the top level element in the XML structure of the request. In SRU, all of the information as to how to process the request must be carried in the URL. Until such time as the SOAP community define a standard mechanism for this, SRU has an 'operation' parameter.

Only available for SRU, the 'operation' parameter carries the name of the operation to be carried out. This is the base part of the message name, so currently defined operations are 'searchRetrieve', 'explain', and 'scan', not to be confused with the name of the request.

For example:

  http://srw.cheshire3.org/l5r?operation=searchRetrieve&query=sword&maximumRecords=10

Additional Response Parameters

nextRecordPosition

An integer recording the position of the next record within the result set may be supplied following the records field. This is only returned in the searchRetrieveResponse.

echoedRequest

Within the echoedRequest element are the parameters supplied to the server in the request in elements named after the parameters, just as if they had been supplied in a SOAP based request. The query should also be echoed in an 'xQuery' element, containing the XCQL representation of the CQL query string. This enables an SRU client to easily construct the query again, perhaps to retrieve the next set of records in the result set. Likewise, the sortKeys should be returned in both string and xSortKeys forms. The scanClause in the scan operation should be returned in xScanClause in XCQL.

Example:

<echoedRequest>
  <query>dc.title = cat</query>
  <xQuery>
    <searchClause>
      <index>dc.title</index>
      <relation>
        <value>=</value>
      </relation>
      <term>cat</term>
  </xQuery>
  <maximumRecords>10</maximumRecords>
  <recordSchema>DC</recordSchema>
  <sortKeys>title,dc</sortKeys>
  <xSortKeys>
    <sortKey>
      <path>title</path>
      <schema>dc</path>
    </sortKey>
  </xSortKeys>
  <startRecord>1</startRecord>
</echoedRequest>

Diagnostics

There are some error conditions which may occur in SRU which will not occur in SRW. The SOAP parser will not accept an unknown operation, or a badly formed message. However an SRU server should be prepared to receive strange values in its parameters.

If an unknown operation is requested, then the server may return an explainResponse with diagnostic 4 (Unsupported Operation). If one of the parameter values is incomprehensible, for example a maximumRecords of 'fish', then diagnostic 6 is available. Diagnostic 7 is also useful for when mandatory parameters are omitted.