1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
2 "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
4 <!ENTITY % local SYSTEM "local.ent">
6 <!ENTITY % entities SYSTEM "entities.ent">
8 <!ENTITY % idcommon SYSTEM "common/common.ent">
11 <!-- $Id: pazpar2_protocol.xml,v 1.9 2007-06-22 13:18:23 adam Exp $ -->
12 <refentry id="pazpar2_protocol">
14 <productname>Pazpar2</productname>
15 <productnumber>&version;</productnumber>
18 <refentrytitle>Pazpar2 protocol</refentrytitle>
19 <manvolnum>7</manvolnum>
23 <refname>pazpar2_protocol</refname>
24 <refpurpose>The webservice protocol of Pazpar2</refpurpose>
27 <refsect1><title>DESCRIPTION</title>
29 Webservice requests are any that refer to filename "search.pz2". Arguments
30 are GET-style parameters. Argument 'command' is always required and specifies
31 the operation to perform. Any request not recognized as a webservice
32 request is forwarded to the HTTP server specified in the configuration
33 using the proxy setting.
34 This way, a regular webserver can host the user interface (itself dynamic
35 or static HTML), and AJAX-style calls can be used from JS (or any other client-based
36 scripting environment) to interact with the search logic in Pazpar2.
39 Each command is described in sub sections to follow.
41 <refsect2 id="command-init"><title>init</title>
43 Initializes a session.
44 Returns session ID to be used in subsequent requests.
49 search.pz2?command=init
58 <session>2044502273</session>
62 The init command may take a number of setting parameters, similar to
63 the 'settings' command described below. These settings are immediately
64 applied to the new session.
68 <refsect2 id="command-ping"><title>ping</title>
70 Keeps a session alive. An idle session will time out after one minute.
71 The ping command can be used to keep the session alive absent other
73 It is suggested that any browser client have a simple alarm handler which
74 sends a ping every 50 seconds or so once a session has been initialized.
79 search.pz?command=ping&session=2044502273
90 <refsect2 id="command-settings">
91 <title>settings</title>
93 The settings command applies session-specific settings to one or more
94 databases. A typical function of this is to enable access to
95 restricted resources for registered users, or to set a user- or
96 library-specific username/password to use against a target. Each
97 setting parameter has the form name[target]=value, where name is the
98 name of the setting (e.g. pz:authentication), target is a target ID,
99 or possibly a wildcard, and value is the desired value for the
104 Because the settings command manipulates potentially sensitive
105 information, it is possible to configure Pazpar2 to only allow access
106 to this command from a trusted site -- usually from server-side
107 scripting, which in turn is responsible for authenticating the user,
108 and possibly determining which resources he has access to, etc.
113 As a shortcut, it is also possible to override settings directly in
121 search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
132 <refsect2 id="command-search"><title>search</title>
134 Launches a search, parameters:
159 search.pz2?session=2044502273&command=search&query=computer+science
171 <refsect2 id="command-stat">
174 Provides status information about an ongoing search. Parameters:
191 search.pz2?session=2044502273&command=stat
196 <activeclients>3</activeclients>
197 <hits>7</hits> -- Total hitcount
198 <records>7</records> -- Total number of records fetched in last query
199 <clients>1</clients> -- Total number of associated clients
200 <unconnected>0</unconnected> -- Number of disconnected clients
201 <connecting>0</connecting> -- Number of clients in connecting state
202 <initializing>0</initializing> -- Number of clients initializing
203 <searching>0</searching> -- ... searching
204 <presenting>0</presenting> -- ... presenting
205 <idle>1</idle> -- ... idle (not doing anything)
206 <failed>0</failed> -- ... Connection failed
207 <error>0</error> -- ... Error was produced somewhere
213 <refsect2 id="command-show">
216 Shows records retrieved. Parameters:
230 <para>First record to show - 0-indexed.</para>
238 Number of records to show If omitted, 20 is used.
247 If block is set to 1, the command will hang until there are records ready
248 to display. Use this to show first records rapidly without
249 requiring rapid polling.
258 Specifies sort criteria. The argument is a comma-separated list
259 (no whitespace allowed) of sort fields, with the highest-priority
260 field first. A sort field may be followed by a colon followed by
261 the number '0' or '1', indicating whether results should be sorted in
262 increasing or decreasing order according to that field. 0==Decreasing is
273 search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
279 <activeclients>3</activeclients> -- How many clients are still working
280 <merged>6</merged> -- Number of merged records
281 <total>7</total> -- Total of all hitcounts
282 <start>0</start> -- The start number you requested
283 <num>2</num> -- Number of records retrieved
285 <md-title>How to program a computer, by Jack Collins</md-title>
286 <count>2</count> -- Number of merged records
287 <recid>6</recid> -- Record ID for this record
291 Computer processing of dynamic images from an Anger scintillation camera :
292 the proceedings of a workshop /
301 <refsect2 id="command-record">
302 <title>record</title>
304 Retrieves a detailed record. Parameters:
320 record ID as provided by the
321 <link linkend="command-show">show</link> command.
330 search.pz2?session=605047297&command=record&id=3
338 The Puget Sound Region : a portfolio of thematic computer maps /
340 <md-date>1974</md-date>
341 <md-author>Mairs, John W.</md-author>
342 <md-subject>Cartography</md-subject>
349 <refsect2 id="command-termlist">
350 <title>termlist</title>
352 Retrieves term list(s). Parameters:
355 name -- comma-separated list of termlist names (default "subject")
361 search.pz2?session=2044502273&command=termlist&name=author,subject
366 <activeclients>3</activeclients>
369 <name>Donald Knuth</name>
370 <frequency>10</frequency>
373 <name>Robert Pirsig</name>
374 <frequency>2</frequency>
377 <list name="subject">
379 <name>Computer programming</name>
380 <frequency>10</frequency>
388 For the special termlist name "xtargets", results
389 are returned about the targets which have returned the most hits.
390 The 'term' subtree has additional elements,
391 specifically a state and diagnostic field (in the example below, a
392 target ID is returned in place of 'name'.
393 This may or may not change later.
399 <name>library2.mcmaster.ca</name>
400 <frequency>11734</frequency> -- Number of hits
401 <state>Client_Idle</state> -- See the description of 'bytarget' below
402 <diagnostic>0</diagnostic> -- Z39.50 diagnostic codes
409 <refsect2 id="command-bytarget">
410 <title>bytarget</title>
412 Returns information about the status of each active client. Parameters:
428 search.pz2?session=605047297&command=record&id=3
437 <id>z3950.loc.gov/voyager/</id>
439 <diagnostic>0</diagnostic>
440 <records>65</records>
441 <state>Client_Presenting</state>
443 <!-- ... more target nodes below as necessary -->
447 The following client states are defined: Client_Connecting,
448 Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
449 Client_Searching, Client_Presenting, Client_Error, Client_Failed,
450 Client_Disconnected, Client_Stopped.
457 <!-- Keep this comment at the end of the file
462 sgml-minimize-attributes:nil
463 sgml-always-quote-attributes:t
466 sgml-parent-document:nil
467 sgml-local-catalogs: nil
468 sgml-namecase-general:t