Name

pazpar2_protocol — The webservice protocol of Pazpar2

DESCRIPTION

Webservice requests are any that refer to filename "search.pz2". Arguments are GET-style parameters. Argument 'command' is always required and specifies the operation to perform. Any request not recognized as a webservice request is forwarded to the HTTP server specified in the configuration using the proxy setting. This way, a regular webserver can host the user interface (itself dynamic or static HTML), and Ajax-style calls can be used from JS (or any other client-based scripting environment) to interact with the search logic in Pazpar2.

Each command is described in sub sections to follow.

init

Initializes a session. Returns session ID to be used in subsequent requests. If a server ID is given in the Pazpar2 server section, then a period (.) and the server ID is appended to the session ID.

Example:

     search.pz2?command=init
    

Response:

    <init>
     <status>OK</status>
     <session>2044502273</session>
    </init>

The init command may take a number of setting parameters, similar to the 'settings' command described below. These settings are immediately applied to the new session. Other parameters for init are:

clear

If this is defined and the value is non-zero, the session will not use the predefined databases in the configuration; only those specified in the settings parameters (per session databases).

service

If this is defined it specifies a service ID. Makes the session use the service with this ID. If this is setting is omitted, the session will use the unnamed service in the Pazpar2 configuration.

ping

Keeps a session alive. An idle session will time out after one minute. The ping command can be used to keep the session alive absent other activity. It is suggested that any browser client have a simple alarm handler which sends a ping every 50 seconds or so once a session has been initialized.

Example:

     search.pz?command=ping&session=2044502273

    

Response:

<ping>
  <status>OK</status>
</ping>

settings

The settings command applies session-specific settings to one or more databases. A typical function of this is to enable access to restricted resources for registered users, or to set a user- or library-specific username/password to use against a target. Each setting parameter has the form name[target]=value, where name is the name of the setting (e.g. pz:authentication), target is a target ID, or possibly a wildcard, and value is the desired value for the setting.

Because the settings command manipulates potentially sensitive information, it is possible to configure Pazpar2 to only allow access to this command from a trusted site -- usually from server-side scripting, which in turn is responsible for authenticating the user, and possibly determining which resources he has access to, etc.

Note

As a shortcut, it is also possible to override settings directly in the init command.

Example:

       search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
      

Response:

<settings>
  <status>OK</status>
</settings>

search

Launches a search, parameters:

session

Session ID

query

CCL query

filter

Limits the search to a given set of targets specified by the filter. The filter consists a comma separated list of setting+operator+args pairs. The setting is a Pazpar2 setting (such as pz:id). The operator is either = (string match) or ~ (substring match). The args is a list of values separated by | (or , one of the values). The idea is that only targets with a setting matching one of the values given will be included in the search.

startrecs

Specifies the first record to retrieve from each target. The first record in a result set for a target is numbered 0, next record is numbered 2. By default maxrecs is 0.

maxrecs

Specifies the maximum number of records to retrieve from each target. The default value is 100. This setting has same meaning as per-target setting pz:maxrecs . If pz:maxrecs is set, it takes precedence over argument maxrecs.

Example:

search.pz2?session=2044502273&command=search&query=computer+science

     

Response:

<search>
  <status>OK</status>
</search>
     

stat

Provides status information about an ongoing search. Parameters:

session

Session ID

Example:

search.pz2?session=2044502273&command=stat
    

Output

<stat>
  <activeclients>3</activeclients>
  <hits>7</hits>                   -- Total hitcount
  <records>7</records>             -- Total number of records fetched in last query
  <clients>1</clients>             -- Total number of associated clients
  <unconnected>0</unconnected>     -- Number of disconnected clients
  <connecting>0</connecting>       -- Number of clients in connecting state
  <initializing>0</initializing>   -- Number of clients initializing
  <searching>0</searching>         -- ... searching
  <presenting>0</presenting>       -- ... presenting
  <idle>1</idle>                   -- ... idle (not doing anything)
  <failed>0</failed>               -- ... Connection failed
  <error>0</error>                 -- ... Error was produced somewhere
</stat>
     

show

Shows records retrieved. Parameters:

session

Session ID

start

First record to show - 0-indexed.

num

Number of records to show If omitted, 20 is used.

block

If block is set to 1, the command will hang until there are records ready to display. Use this to show first records rapidly without requiring rapid polling.

sort

Specifies sort criteria. The argument is a comma-separated list (no whitespace allowed) of sort fields, with the highest-priority field first. A sort field may be followed by a colon followed by the number '0' or '1', indicating whether results should be sorted in increasing or decreasing order according to that field. 0==Decreasing is the default. Sort field names can be any field name designated as a sort field in the pazpar2.cfg file, or the special name 'relevance'.

Example:

search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1

Output:

<show>
  <status>OK</status>
  <activeclients>3</activeclients>     -- How many clients are still working
  <merged>6</merged>                   -- Number of merged records
  <total>7</total>                     -- Total of all hitcounts
  <start>0</start>                     -- The start number you requested
  <num>2</num>                         -- Number of records retrieved
  <hit>
    <md-title>How to program a computer, by Jack Collins</md-title>
    <count>2</count>                   -- Number of merged records 
    <recid>6</recid>                   -- Record ID for this record
  </hit>
  <hit>
    <md-title>
  Computer processing of dynamic images from an Anger scintillation camera :
  the proceedings of a workshop /
    </md-title>
    <recid>2</recid>
  </hit>
</show>
     

record

Retrieves a detailed record. Unlike the show command, this command returns metadata records before merging takes place. Parameters:

session

Session ID

id

record ID as provided by the show command.

offset

This optional parameter is an integer which, when given, makes Pazpar2 return the raw record for a target. The raw record from first target is numbered 0, second numbered 1, etc. When a raw record is returned Pazpar2 will XSLT transform the record but an XML version is returned. All ISO2709 records are returned as MARCXML. OPAC records are returned as YAZ' OPAC with an MARCXML sibling.

When offset is not given the Pazpar2 metadata for the record is returned and with metadata for each targets' data specified in a 'location' list.

syntax

This optional parameter is the record syntax used for raw transfer (i.e. when offset is specified). If syntax is not given, but offset is used, the value of pz:requestsyntax is used.

esn

This optional parameter is the element set name used to retrieval of a raw record (i.e. when offset is specified). If esn is not given, but offset is used, the value of pz:elements is used.

binary

This optional parameter enables "binary" response for retrieval of a raw record (i.e. when offset is specified). For binary responses the record is not converted to XML and the HTTP content type is application/octet-stream.

Example:

search.pz2?session=605047297&command=record&id=3

Example output:

<record>
  <md-title>
	The Puget Sound Region : a portfolio of thematic computer maps /
  </md-title>
  <md-date>1974</md-date>
  <md-author>Mairs, John W.</md-author>
  <md-subject>Cartography</md-subject>
</record>

termlist

Retrieves term list(s). Parameters:

session

Session Id.

name

comma-separated list of termlist names (default "subject")

num

maximum number of entries to return - default is 15.

Example:

search.pz2?session=2044502273&command=termlist&name=author,subject

Output:

<termlist>
  <activeclients>3</activeclients>
  <list name="author">
    <term>
      <name>Donald Knuth</name>
      <frequency>10</frequency>
    </term>
      <term>
      <name>Robert Pirsig</name>
      <frequency>2</frequency>
    </term>
  </list>
  <list name="subject">
    <term>
      <name>Computer programming</name>
      <frequency>10</frequency>
    </term>
  </list>
</termlist>

For the special termlist name "xtargets", results are returned about the targets which have returned the most hits. The 'term' subtree has additional elements, specifically a state and diagnostic field (in the example below, a target ID is returned in place of 'name'. This may or may not change later.

Example

<term>
  <name>library2.mcmaster.ca</name>
  <frequency>11734</frequency>         -- Number of hits
  <state>Client_Idle</state>           -- See the description of 'bytarget' below
  <diagnostic>0</diagnostic>           -- Z39.50 diagnostic codes
</term>

bytarget

Returns information about the status of each active client. Parameters:

session

Session Id.

Example:

search.pz2?session=605047297&command=bytarget&id=3

Example output:

<bytarget>
  <status>OK</status>
  <target>
    <id>z3950.loc.gov/voyager/</id>
    <hits>10000</hits>
    <diagnostic>0</diagnostic>
    <records>65</records>
    <state>Client_Presenting</state>
  </target>
  <!-- ... more target nodes below as necessary -->
</bytarget>

The following client states are defined: Client_Connecting, Client_Connected, Client_Idle, Client_Initializing, Client_Searching, Client_Searching, Client_Presenting, Client_Error, Client_Failed, Client_Disconnected, Client_Stopped, Client_Continue.

SEE ALSO

Pazpar2: pazpar2(8)

Pazpar2 Configuration: pazpar2_conf(5)