Ready to Learn?Ex Libris products all provide open APIs

Search API

Overview

The Summon Search API is a service that exposes all of the search capabilities of Summon. The API is an HTTP-based service and supports requests via the HTTP GET and POST methods. Currently there are two available response formats: XML and JSON. All requests to the API require authentication via private-key digest. The API receives requests and returns responses encoded in UTF-8. The data that can be retrieved from the Search API include meta documents, facet counts and spelling suggestions.

In addition to the traditional parameter-based query system, the Search API includes a new command-based query system that can be used standalone, or in conjunction with parameters. Commands provide some unique benefits over raw parameters, since they can provide additional information to the API about the action being performed. When the API knows about actions being performed by the client it can execute common search logic, such as paging and did you mean, on the client's behalf. This can greatly simplify the ease and speed of client implementation. For more specific information on the command system, see Commands.

There are four parts to making a Search API request:

  1. Build the URL query string;
  2. Build the HTTP request headers;
  3. Build an authentication digest based on the query string and headers; and
  4. Parse the response and handle any errors.

Query String

Queries are comprised of parameters, commands and tokens, and follow the standard URL format (key=value&anotherKey=otherValue). All queries must be properly URL encoded using UTF-8 character encoding. Query parameter values, and command argument values, contain special characters that will need to be escaped before URL encoding. Some parameters, such as the text query parameter, accept Lucene-specific query syntax, which will need to be escaped as well.

Characters may be escaped with the backslash ('\') character. For all parameter values, and command arguments except q and fq, the characters that must be escaped include: ,:()${}. For parameters and arguments that hold Lucene query syntax, characters that may need to be escaped include: +-&|!(){}[]^"~?:\. Lucene special characters only need to be escaped if their special meaning was not intended. If Lucene escaping and regular escaping are both needed, as in the setTextQuery() command, the Lucene escaping must be performed before regular escaping.

Example - Constructing a query URL

Query for:

  Probability models of recidivism: an exploration

Filter by:

  Author: Linster, Richard L

Text Query:

  Probability models of recidivism\: an exploration

  Note that ':' is escaped in a Lucene query, but no other escaping is needed for the q parameter

Text Filter:

  Author:(Linster, Richard L)

Add Text Filter Command After Escaping:

  addTextFilter(Author\:\(Linster\, Richard L\))

  Note that ':', ',', '(' and ')' are escaped

URL query string before encoding:

  q=Probability models of recidivism\: an exploration&cmd=addTextFilter(Author\:\(Linster\, Richard L\))

URL query string encoded:

  q=Probability+models+of+recidivism%5C%3A+an+exploration&cmd=addTextFilter%28Author%5C%3A%5C%28Linster%5C%2C+Richard+L%5C%29%29

For more specific information on building the URL query string, see: Parameters, Commands and Tokens.


Request Headers

The Search API uses five request headers:

  • Accept
  • x-summon-date
  • Host
  • Authorization
  • x-summon-session-id

The Accept header is used to tell the API which response type to return. Currently supported values are application/xml and application/json. This header is included when building the authentication digest.

The x-summon-date header is used during the authentication process, and is checked against the timestamp on the server. The date value is in standard Date format as defined in RFC 2616. This header is included when building the authentication digest.

The Host header is a required HTTP header and is used internally to service the request. It follows the standard format for the HTTP Host header, as defined in RFC 2616. This header is included when building the authentication digest.

The Authorization header is used for both authentication and authorization. The header contains an access ID and a digest of specific request attributes computed with a secret key corresponding to the access ID. The server authenticates a request by comparing the digest from the Authorization header with a server-computed digest.

The x-summon-session-id header is an optional header that is used to link user sessions to API sessions. The session ID is returned in the response, and if this header is not present, a session ID will be generated for the request. If the x-summon-session-id is not sent with the first API request, then the generated session ID from the response should be sent in the x-summon-session-id header on all subsequent requests.

Example - Search API request headers

               Host: api.summon.serialssolutions.com
             Accept: application/xml
      x-summon-date: Mon, 29 Jun 2009 23:07:20 GMT
      Authorization: Summon test;TUDe5VCP520njOGCP8bg3uKR6OM=
x-summon-session-id: 0iy5u3VAkySQ3/Nbd7TT+WKdEYk=

Authentication Digest

Authentication digests are HMAC-SHA1, Base64-encoded strings. They are computed from various request elements using a secret key. Computed digests are time sensitive, and will expire once their computed time is too different from the server time. For specific details on building the authentication digest, see Authentication.

Response

All responses from the Search API are UTF-8 encoded. There are currently two response formats supported: custom JSON and custom XML. The HTTP Accept header determines which response type is returned.

Two conditions may occur before a request is processed that will cause no response to be returned:

  • If the HTTP Accept header specifies a format that cannot be satisfied by the API, the HTTP response status code will be 406 -- Not Acceptable.
  • If authentication fails for any reason, the HTTP response status code will be 401 -- Unauthorized.

If the API is capable of handling the request, and authentication passes, a response object is returned in either XML or JSON. The response object contains the results of the query, as well as metadata about the query that can be used either for display purposes or for further refinement of the query. The response may also contain more descriptive errors than the HTTP status errors. For more information on the response, see Response and Errors.