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. If
45 a server ID is given in the Pazpar2 server section, then a
46 period (.) and the server ID is appended to the session ID.
51 search.pz2?command=init
60 <session>2044502273</session>
64 The init command may take a number of setting parameters, similar to
65 the 'settings' command described below. These settings are immediately
66 applied to the new session. Other parameters for init are:
72 If this is defined and the value is non-zero, the session will
73 not use the predefined databases in the configuration; only those
74 specified in the settings parameters (per session databases).
83 If this is defined it specifies a service ID. Makes the session use
84 the service with this ID. If this is setting is omitted, the
85 session will use the unnamed service in the Pazpar2 configuration.
93 <refsect2 id="command-ping"><title>ping</title>
95 Keeps a session alive. An idle session will time out after one minute.
96 The ping command can be used to keep the session alive absent other
98 It is suggested that any browser client have a simple alarm handler which
99 sends a ping every 50 seconds or so once a session has been initialized.
104 search.pz?command=ping&session=2044502273
115 <refsect2 id="command-settings">
116 <title>settings</title>
118 The settings command applies session-specific settings to one or more
119 databases. A typical function of this is to enable access to
120 restricted resources for registered users, or to set a user- or
121 library-specific username/password to use against a target. Each
122 setting parameter has the form name[target]=value, where name is the
123 name of the setting (e.g. pz:authentication), target is a target ID,
124 or possibly a wildcard, and value is the desired value for the
129 Because the settings command manipulates potentially sensitive
130 information, it is possible to configure Pazpar2 to only allow access
131 to this command from a trusted site -- usually from server-side
132 scripting, which in turn is responsible for authenticating the user,
133 and possibly determining which resources he has access to, etc.
138 As a shortcut, it is also possible to override settings directly in
146 search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
157 <refsect2 id="command-search"><title>search</title>
159 Launches a search, parameters:
182 Limits the search to a given set of targets specified by the
183 filter. The filter consists a comma separated list of
184 setting+operator+args pairs. The setting is a Pazpar2 setting
185 (such as <literal>pz:id</literal>).
186 The operator is either = (string match)
187 or ~ (substring match). The args is a list of values separated
188 by | (or , one of the values). The idea is that only targets
189 with a setting matching one of the values given will be included
195 <term>startrecs</term>
198 Specifies the first record to retrieve from each target.
199 The first record in a result set for a target is numbered 0, next
200 record is numbered 2. By default maxrecs is 0.
208 Specifies the maximum number of records to retrieve from each
209 target. The default value is 100. This setting has same meaning
210 as per-target setting pz:maxrecs . If pz:maxrecs is set, it takes
211 precedence over argument maxrecs.
221 search.pz2?session=2044502273&command=search&query=computer+science
233 <refsect2 id="command-stat">
236 Provides status information about an ongoing search. Parameters:
253 search.pz2?session=2044502273&command=stat
258 <activeclients>3</activeclients>
259 <hits>7</hits> -- Total hitcount
260 <records>7</records> -- Total number of records fetched in last query
261 <clients>1</clients> -- Total number of associated clients
262 <unconnected>0</unconnected> -- Number of disconnected clients
263 <connecting>0</connecting> -- Number of clients in connecting state
264 <initializing>0</initializing> -- Number of clients initializing
265 <searching>0</searching> -- ... searching
266 <presenting>0</presenting> -- ... presenting
267 <idle>1</idle> -- ... idle (not doing anything)
268 <failed>0</failed> -- ... Connection failed
269 <error>0</error> -- ... Error was produced somewhere
275 <refsect2 id="command-show">
278 Shows records retrieved. Parameters:
292 <para>First record to show - 0-indexed.</para>
300 Number of records to show If omitted, 20 is used.
309 If block is set to 1, the command will hang until there are records ready
310 to display. Use this to show first records rapidly without
311 requiring rapid polling.
320 Specifies sort criteria. The argument is a comma-separated list
321 (no whitespace allowed) of sort fields, with the highest-priority
322 field first. A sort field may be followed by a colon followed by
323 the number '0' or '1', indicating whether results should be sorted in
324 increasing or decreasing order according to that field. 0==Decreasing is
325 the default. Sort field names can be any field name designated as a sort field
326 in the pazpar2.cfg file, or the special name 'relevance'.
336 search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
342 <activeclients>3</activeclients> -- How many clients are still working
343 <merged>6</merged> -- Number of merged records
344 <total>7</total> -- Total of all hitcounts
345 <start>0</start> -- The start number you requested
346 <num>2</num> -- Number of records retrieved
348 <md-title>How to program a computer, by Jack Collins</md-title>
349 <count>2</count> -- Number of merged records
350 <recid>6</recid> -- Record ID for this record
354 Computer processing of dynamic images from an Anger scintillation camera :
355 the proceedings of a workshop /
364 <refsect2 id="command-record">
365 <title>record</title>
367 Retrieves a detailed record. Unlike the
368 <link linkend="command-show">show</link> command, this command
369 returns metadata records before merging takes place. Parameters:
385 record ID as provided by the
386 <link linkend="command-show">show</link> command.
395 This optional parameter is an integer which, when given, makes
396 Pazpar2 return the raw record for a target. The raw record
397 from first target is numbered 0, second numbered 1, etc.
398 When a raw record is returned Pazpar2 will XSLT transform the
399 record but an XML version is returned. All ISO2709 records are
400 returned as MARCXML. OPAC records are returned as YAZ'
401 OPAC with an MARCXML sibling.
404 When offset is not given the Pazpar2 metadata for the record
405 is returned and with metadata for each targets' data specified
406 in a 'location' list.
415 This optional parameter is the record syntax used for raw
416 transfer (i.e. when offset is specified). If syntax is not given,
417 but offset is used, the value of pz:requestsyntax is used.
426 This optional parameter is the element set name used to retrieval
427 of a raw record (i.e. when offset is specified).
428 If esn is not given, but offset is used, the value of pz:elements
438 This optional parameter enables "binary" response for retrieval
439 of a raw record (i.e. when offset is specified). For binary
440 responses the record is <emphasis>not</emphasis> converted to
441 XML and the HTTP content type is application/octet-stream.
451 search.pz2?session=605047297&command=record&id=3
459 The Puget Sound Region : a portfolio of thematic computer maps /
461 <md-date>1974</md-date>
462 <md-author>Mairs, John W.</md-author>
463 <md-subject>Cartography</md-subject>
469 <refsect2 id="command-termlist">
470 <title>termlist</title>
472 Retrieves term list(s). Parameters:
487 comma-separated list of termlist names (default "subject")
496 search.pz2?session=2044502273&command=termlist&name=author,subject
501 <activeclients>3</activeclients>
504 <name>Donald Knuth</name>
505 <frequency>10</frequency>
508 <name>Robert Pirsig</name>
509 <frequency>2</frequency>
512 <list name="subject">
514 <name>Computer programming</name>
515 <frequency>10</frequency>
523 For the special termlist name "xtargets", results
524 are returned about the targets which have returned the most hits.
525 The 'term' subtree has additional elements,
526 specifically a state and diagnostic field (in the example below, a
527 target ID is returned in place of 'name'.
528 This may or may not change later.
534 <name>library2.mcmaster.ca</name>
535 <frequency>11734</frequency> -- Number of hits
536 <state>Client_Idle</state> -- See the description of 'bytarget' below
537 <diagnostic>0</diagnostic> -- Z39.50 diagnostic codes
544 <refsect2 id="command-bytarget">
545 <title>bytarget</title>
547 Returns information about the status of each active client. Parameters:
563 search.pz2?session=605047297&command=bytarget&id=3
572 <id>z3950.loc.gov/voyager/</id>
574 <diagnostic>0</diagnostic>
575 <records>65</records>
576 <state>Client_Presenting</state>
578 <!-- ... more target nodes below as necessary -->
582 The following client states are defined: Client_Connecting,
583 Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
584 Client_Searching, Client_Presenting, Client_Error, Client_Failed,
585 Client_Disconnected, Client_Stopped, Client_Continue.
590 <refsect1><title>SEE ALSO</title>
594 <refentrytitle>pazpar2</refentrytitle>
595 <manvolnum>8</manvolnum>
599 Pazpar2 Configuration:
601 <refentrytitle>pazpar2_conf</refentrytitle>
602 <manvolnum>5</manvolnum>
608 <!-- Keep this comment at the end of the file
613 sgml-minimize-attributes:nil
614 sgml-always-quote-attributes:t
617 sgml-parent-document:nil
618 sgml-local-catalogs: nil
619 sgml-namecase-general:t