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 <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. Other parameters for init are:
70 If this is defined and the value is non-zero, the session will
71 not use the predefined databases in the configuration; only those
72 specified in the settings parameters (per session databases).
81 If this is defined it specifies a service ID. Makes the session use
82 the service with this ID. If this is setting is omitted, the
83 session will use the unnamed service in the Pazpar2 configuration.
91 <refsect2 id="command-ping"><title>ping</title>
93 Keeps a session alive. An idle session will time out after one minute.
94 The ping command can be used to keep the session alive absent other
96 It is suggested that any browser client have a simple alarm handler which
97 sends a ping every 50 seconds or so once a session has been initialized.
102 search.pz?command=ping&session=2044502273
113 <refsect2 id="command-settings">
114 <title>settings</title>
116 The settings command applies session-specific settings to one or more
117 databases. A typical function of this is to enable access to
118 restricted resources for registered users, or to set a user- or
119 library-specific username/password to use against a target. Each
120 setting parameter has the form name[target]=value, where name is the
121 name of the setting (e.g. pz:authentication), target is a target ID,
122 or possibly a wildcard, and value is the desired value for the
127 Because the settings command manipulates potentially sensitive
128 information, it is possible to configure Pazpar2 to only allow access
129 to this command from a trusted site -- usually from server-side
130 scripting, which in turn is responsible for authenticating the user,
131 and possibly determining which resources he has access to, etc.
136 As a shortcut, it is also possible to override settings directly in
144 search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
155 <refsect2 id="command-search"><title>search</title>
157 Launches a search, parameters:
180 Limits the search to a given set of targets specified by the
181 filter. The filter consists a comma separated list of
182 setting+operator+args pairs. The setting is a Pazpar2 setting
183 (such as <literal>pz:id</literal>).
184 The operator is either = (string match)
185 or ~ (substring match). The args is a list of values separated
186 by | (or , one of the values). The idea is that only targets
187 with a setting matching one of the values given will be included
193 <term>startrecs</term>
196 Specifies the first record to retrieve from each target.
197 The first record in a result set for a target is numbered 0, next
198 record is numbered 2. By default maxrecs is 0.
206 Specifies the maximum number of records to retrieve from each
207 target. The default value is 100. This setting has same meaning
208 as per-target setting pz:maxrecs . If pz:maxrecs is set, it takes
209 precedence over argument maxrecs.
219 search.pz2?session=2044502273&command=search&query=computer+science
231 <refsect2 id="command-stat">
234 Provides status information about an ongoing search. Parameters:
251 search.pz2?session=2044502273&command=stat
256 <activeclients>3</activeclients>
257 <hits>7</hits> -- Total hitcount
258 <records>7</records> -- Total number of records fetched in last query
259 <clients>1</clients> -- Total number of associated clients
260 <unconnected>0</unconnected> -- Number of disconnected clients
261 <connecting>0</connecting> -- Number of clients in connecting state
262 <initializing>0</initializing> -- Number of clients initializing
263 <searching>0</searching> -- ... searching
264 <presenting>0</presenting> -- ... presenting
265 <idle>1</idle> -- ... idle (not doing anything)
266 <failed>0</failed> -- ... Connection failed
267 <error>0</error> -- ... Error was produced somewhere
273 <refsect2 id="command-show">
276 Shows records retrieved. Parameters:
290 <para>First record to show - 0-indexed.</para>
298 Number of records to show If omitted, 20 is used.
307 If block is set to 1, the command will hang until there are records ready
308 to display. Use this to show first records rapidly without
309 requiring rapid polling.
318 Specifies sort criteria. The argument is a comma-separated list
319 (no whitespace allowed) of sort fields, with the highest-priority
320 field first. A sort field may be followed by a colon followed by
321 the number '0' or '1', indicating whether results should be sorted in
322 increasing or decreasing order according to that field. 0==Decreasing is
323 the default. Sort field names can be any field name designated as a sort field
324 in the pazpar2.cfg file, or the special name 'relevance'.
334 search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
340 <activeclients>3</activeclients> -- How many clients are still working
341 <merged>6</merged> -- Number of merged records
342 <total>7</total> -- Total of all hitcounts
343 <start>0</start> -- The start number you requested
344 <num>2</num> -- Number of records retrieved
346 <md-title>How to program a computer, by Jack Collins</md-title>
347 <count>2</count> -- Number of merged records
348 <recid>6</recid> -- Record ID for this record
352 Computer processing of dynamic images from an Anger scintillation camera :
353 the proceedings of a workshop /
362 <refsect2 id="command-record">
363 <title>record</title>
365 Retrieves a detailed record. Unlike the
366 <link linkend="command-show">show</link> command, this command
367 returns metadata records before merging takes place. Parameters:
383 record ID as provided by the
384 <link linkend="command-show">show</link> command.
393 This optional parameter is an integer which, when given, makes
394 Pazpar2 return the raw record for a target. The raw record
395 from first target is numbered 0, second numbered 1, etc.
396 When a raw record is returned Pazpar2 will XSLT transform the
397 record but an XML version is returned. All ISO2709 records are
398 returned as MARCXML. OPAC records are returned as YAZ'
399 OPAC with an MARCXML sibling.
402 When offset is not given the Pazpar2 metadata for the record
403 is returned and with metadata for each targets' data specified
404 in a 'location' list.
413 This optional parameter is the record syntax used for raw
414 transfer (i.e. when offset is specified). If syntax is not given,
415 but offset is used, the value of pz:requestsyntax is used.
424 This optional parameter is the element set name used to retrieval
425 of a raw record (i.e. when offset is specified).
426 If esn is not given, but offset is used, the value of pz:elements
436 This optional parameter enables "binary" response for retrieval
437 of a raw record (i.e. when offset is specified). For binary
438 responses the record is <emphasis>not</emphasis> converted to
439 XML and the HTTP content type is application/octet-stream.
449 search.pz2?session=605047297&command=record&id=3
457 The Puget Sound Region : a portfolio of thematic computer maps /
459 <md-date>1974</md-date>
460 <md-author>Mairs, John W.</md-author>
461 <md-subject>Cartography</md-subject>
467 <refsect2 id="command-termlist">
468 <title>termlist</title>
470 Retrieves term list(s). Parameters:
485 comma-separated list of termlist names (default "subject")
494 search.pz2?session=2044502273&command=termlist&name=author,subject
499 <activeclients>3</activeclients>
502 <name>Donald Knuth</name>
503 <frequency>10</frequency>
506 <name>Robert Pirsig</name>
507 <frequency>2</frequency>
510 <list name="subject">
512 <name>Computer programming</name>
513 <frequency>10</frequency>
521 For the special termlist name "xtargets", results
522 are returned about the targets which have returned the most hits.
523 The 'term' subtree has additional elements,
524 specifically a state and diagnostic field (in the example below, a
525 target ID is returned in place of 'name'.
526 This may or may not change later.
532 <name>library2.mcmaster.ca</name>
533 <frequency>11734</frequency> -- Number of hits
534 <state>Client_Idle</state> -- See the description of 'bytarget' below
535 <diagnostic>0</diagnostic> -- Z39.50 diagnostic codes
542 <refsect2 id="command-bytarget">
543 <title>bytarget</title>
545 Returns information about the status of each active client. Parameters:
561 search.pz2?session=605047297&command=bytarget&id=3
570 <id>z3950.loc.gov/voyager/</id>
572 <diagnostic>0</diagnostic>
573 <records>65</records>
574 <state>Client_Presenting</state>
576 <!-- ... more target nodes below as necessary -->
580 The following client states are defined: Client_Connecting,
581 Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
582 Client_Searching, Client_Presenting, Client_Error, Client_Failed,
583 Client_Disconnected, Client_Stopped, Client_Continue.
588 <refsect1><title>SEE ALSO</title>
592 <refentrytitle>pazpar2</refentrytitle>
593 <manvolnum>8</manvolnum>
597 Pazpar2 Configuration:
599 <refentrytitle>pazpar2_conf</refentrytitle>
600 <manvolnum>5</manvolnum>
606 <!-- Keep this comment at the end of the file
611 sgml-minimize-attributes:nil
612 sgml-always-quote-attributes:t
615 sgml-parent-document:nil
616 sgml-local-catalogs: nil
617 sgml-namecase-general:t