1 <?xml version="1.0" standalone="no"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
5 <!ENTITY % local SYSTEM "local.ent">
7 <!ENTITY % entities SYSTEM "entities.ent">
9 <!ENTITY % idcommon SYSTEM "common/common.ent">
12 <!-- $Id: pazpar2_protocol.xml,v 1.12 2007-07-02 20:02:48 adam Exp $ -->
13 <refentry id="pazpar2_protocol">
15 <productname>Pazpar2</productname>
16 <productnumber>&version;</productnumber>
19 <refentrytitle>Pazpar2 protocol</refentrytitle>
20 <manvolnum>7</manvolnum>
24 <refname>pazpar2_protocol</refname>
25 <refpurpose>The webservice protocol of Pazpar2</refpurpose>
28 <refsect1><title>DESCRIPTION</title>
30 Webservice requests are any that refer to filename "search.pz2". Arguments
31 are GET-style parameters. Argument 'command' is always required and specifies
32 the operation to perform. Any request not recognized as a webservice
33 request is forwarded to the HTTP server specified in the configuration
34 using the proxy setting.
35 This way, a regular webserver can host the user interface (itself dynamic
36 or static HTML), and AJAX-style calls can be used from JS (or any other client-based
37 scripting environment) to interact with the search logic in Pazpar2.
40 Each command is described in sub sections to follow.
42 <refsect2 id="command-init"><title>init</title>
44 Initializes a session.
45 Returns session ID to be used in subsequent requests.
50 search.pz2?command=init
59 <session>2044502273</session>
63 The init command may take a number of setting parameters, similar to
64 the 'settings' command described below. These settings are immediately
65 applied to the new session. Other parameters for init are:
71 If this is defined and the value is non-zero, the session will
72 not use the predefined databases in the configuration; only those
73 specified in the settings parameters (per session databases).
81 <refsect2 id="command-ping"><title>ping</title>
83 Keeps a session alive. An idle session will time out after one minute.
84 The ping command can be used to keep the session alive absent other
86 It is suggested that any browser client have a simple alarm handler which
87 sends a ping every 50 seconds or so once a session has been initialized.
92 search.pz?command=ping&session=2044502273
103 <refsect2 id="command-settings">
104 <title>settings</title>
106 The settings command applies session-specific settings to one or more
107 databases. A typical function of this is to enable access to
108 restricted resources for registered users, or to set a user- or
109 library-specific username/password to use against a target. Each
110 setting parameter has the form name[target]=value, where name is the
111 name of the setting (e.g. pz:authentication), target is a target ID,
112 or possibly a wildcard, and value is the desired value for the
117 Because the settings command manipulates potentially sensitive
118 information, it is possible to configure Pazpar2 to only allow access
119 to this command from a trusted site -- usually from server-side
120 scripting, which in turn is responsible for authenticating the user,
121 and possibly determining which resources he has access to, etc.
126 As a shortcut, it is also possible to override settings directly in
134 search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
145 <refsect2 id="command-search"><title>search</title>
147 Launches a search, parameters:
172 search.pz2?session=2044502273&command=search&query=computer+science
184 <refsect2 id="command-stat">
187 Provides status information about an ongoing search. Parameters:
204 search.pz2?session=2044502273&command=stat
209 <activeclients>3</activeclients>
210 <hits>7</hits> -- Total hitcount
211 <records>7</records> -- Total number of records fetched in last query
212 <clients>1</clients> -- Total number of associated clients
213 <unconnected>0</unconnected> -- Number of disconnected clients
214 <connecting>0</connecting> -- Number of clients in connecting state
215 <initializing>0</initializing> -- Number of clients initializing
216 <searching>0</searching> -- ... searching
217 <presenting>0</presenting> -- ... presenting
218 <idle>1</idle> -- ... idle (not doing anything)
219 <failed>0</failed> -- ... Connection failed
220 <error>0</error> -- ... Error was produced somewhere
226 <refsect2 id="command-show">
229 Shows records retrieved. Parameters:
243 <para>First record to show - 0-indexed.</para>
251 Number of records to show If omitted, 20 is used.
260 If block is set to 1, the command will hang until there are records ready
261 to display. Use this to show first records rapidly without
262 requiring rapid polling.
271 Specifies sort criteria. The argument is a comma-separated list
272 (no whitespace allowed) of sort fields, with the highest-priority
273 field first. A sort field may be followed by a colon followed by
274 the number '0' or '1', indicating whether results should be sorted in
275 increasing or decreasing order according to that field. 0==Decreasing is
286 search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
292 <activeclients>3</activeclients> -- How many clients are still working
293 <merged>6</merged> -- Number of merged records
294 <total>7</total> -- Total of all hitcounts
295 <start>0</start> -- The start number you requested
296 <num>2</num> -- Number of records retrieved
298 <md-title>How to program a computer, by Jack Collins</md-title>
299 <count>2</count> -- Number of merged records
300 <recid>6</recid> -- Record ID for this record
304 Computer processing of dynamic images from an Anger scintillation camera :
305 the proceedings of a workshop /
314 <refsect2 id="command-record">
315 <title>record</title>
317 Retrieves a detailed record. Parameters:
333 record ID as provided by the
334 <link linkend="command-show">show</link> command.
343 search.pz2?session=605047297&command=record&id=3
351 The Puget Sound Region : a portfolio of thematic computer maps /
353 <md-date>1974</md-date>
354 <md-author>Mairs, John W.</md-author>
355 <md-subject>Cartography</md-subject>
361 <refsect2 id="command-termlist">
362 <title>termlist</title>
364 Retrieves term list(s). Parameters:
379 comma-separated list of termlist names (default "subject")
388 search.pz2?session=2044502273&command=termlist&name=author,subject
393 <activeclients>3</activeclients>
396 <name>Donald Knuth</name>
397 <frequency>10</frequency>
400 <name>Robert Pirsig</name>
401 <frequency>2</frequency>
404 <list name="subject">
406 <name>Computer programming</name>
407 <frequency>10</frequency>
415 For the special termlist name "xtargets", results
416 are returned about the targets which have returned the most hits.
417 The 'term' subtree has additional elements,
418 specifically a state and diagnostic field (in the example below, a
419 target ID is returned in place of 'name'.
420 This may or may not change later.
426 <name>library2.mcmaster.ca</name>
427 <frequency>11734</frequency> -- Number of hits
428 <state>Client_Idle</state> -- See the description of 'bytarget' below
429 <diagnostic>0</diagnostic> -- Z39.50 diagnostic codes
436 <refsect2 id="command-bytarget">
437 <title>bytarget</title>
439 Returns information about the status of each active client. Parameters:
455 search.pz2?session=605047297&command=record&id=3
464 <id>z3950.loc.gov/voyager/</id>
466 <diagnostic>0</diagnostic>
467 <records>65</records>
468 <state>Client_Presenting</state>
470 <!-- ... more target nodes below as necessary -->
474 The following client states are defined: Client_Connecting,
475 Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
476 Client_Searching, Client_Presenting, Client_Error, Client_Failed,
477 Client_Disconnected, Client_Stopped.
484 <!-- Keep this comment at the end of the file
489 sgml-minimize-attributes:nil
490 sgml-always-quote-attributes:t
493 sgml-parent-document:nil
494 sgml-local-catalogs: nil
495 sgml-namecase-general:t