1 <?xml version="1.0" standalone="no"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/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>
16 <info><orgname>Index Data</orgname></info>
19 <refentrytitle>Pazpar2 protocol</refentrytitle>
20 <manvolnum>7</manvolnum>
21 <refmiscinfo class="manual">Conventions and miscellaneous</refmiscinfo>
25 <refname>pazpar2_protocol</refname>
26 <refpurpose>The webservice protocol of Pazpar2</refpurpose>
29 <refsect1><title>DESCRIPTION</title>
31 Webservice requests are any that refer to filename "search.pz2". Arguments
32 are GET-style parameters. Argument 'command' is always required and specifies
33 the operation to perform. Any request not recognized as a webservice
34 request is forwarded to the HTTP server specified in the configuration
35 using the proxy setting.
36 This way, a regular webserver can host the user interface (itself dynamic
37 or static HTML), and Ajax-style calls can be used from JS (or any other client-based
38 scripting environment) to interact with the search logic in Pazpar2.
41 Each command is described in sub sections to follow.
43 <refsect2 id="command-init"><title>init</title>
45 Initializes a session.
46 Returns session ID to be used in subsequent requests. If
47 a server ID is given in the Pazpar2 server section, then a
48 period (.) and the server ID is appended to the session ID.
53 search.pz2?command=init
62 <session>2044502273</session>
66 The init command may take a number of setting parameters, similar to
67 the 'settings' command described below. These settings are immediately
68 applied to the new session. Other parameters for init are:
74 If this is defined and the value is non-zero, the session will
75 not use the predefined databases in the configuration; only those
76 specified in the settings parameters (per session databases).
85 If this is defined it specifies a service ID. Makes the session use
86 the service with this ID. If this is setting is omitted, the
87 session will use the unnamed service in the Pazpar2 configuration.
95 <refsect2 id="command-ping"><title>ping</title>
97 Keeps a session alive. An idle session will time out after one minute.
98 The ping command can be used to keep the session alive absent other
100 It is suggested that any browser client have a simple alarm handler which
101 sends a ping every 50 seconds or so once a session has been initialized.
106 search.pz?command=ping&session=2044502273
117 <refsect2 id="command-settings">
118 <title>settings</title>
120 The settings command applies session-specific settings to one or more
121 databases. A typical function of this is to enable access to
122 restricted resources for registered users, or to set a user- or
123 library-specific username/password to use against a target. Each
124 setting parameter has the form name[target]=value, where name is the
125 name of the setting (e.g. pz:authentication), target is a target ID,
126 or possibly a wildcard, and value is the desired value for the
131 Because the settings command manipulates potentially sensitive
132 information, it is possible to configure Pazpar2 to only allow access
133 to this command from a trusted site -- usually from server-side
134 scripting, which in turn is responsible for authenticating the user,
135 and possibly determining which resources he has access to, etc.
140 As a shortcut, it is also possible to override settings directly in
148 search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
159 <refsect2 id="command-search"><title>search</title>
161 Launches a search, parameters:
184 Limits the search to a given set of targets specified by the
185 filter. The filter consists a comma separated list of
186 setting+operator+args pairs. The setting is a Pazpar2 setting
187 (such as <literal>pz:id</literal>).
188 The operator is either = (string match)
189 or ~ (substring match). The args is a list of values separated
190 by | (or , one of the values). The idea is that only targets
191 with a setting matching one of the values given will be included
197 <term>startrecs</term>
200 Specifies the first record to retrieve from each target.
201 The first record in a result set for a target is numbered 0, next
202 record is numbered 2. By default maxrecs is 0.
210 Specifies the maximum number of records to retrieve from each
211 target. The default value is 100. This setting has same meaning
212 as per-target setting pz:maxrecs . If pz:maxrecs is set, it takes
213 precedence over argument maxrecs.
223 search.pz2?session=2044502273&command=search&query=computer+science
235 <refsect2 id="command-stat">
238 Provides status information about an ongoing search. Parameters:
255 search.pz2?session=2044502273&command=stat
260 <activeclients>3</activeclients>
261 <hits>7</hits> -- Total hitcount
262 <records>7</records> -- Total number of records fetched in last query
263 <clients>1</clients> -- Total number of associated clients
264 <unconnected>0</unconnected> -- Number of disconnected clients
265 <connecting>0</connecting> -- Number of clients in connecting state
266 <initializing>0</initializing> -- Number of clients initializing
267 <searching>0</searching> -- ... searching
268 <presenting>0</presenting> -- ... presenting
269 <idle>1</idle> -- ... idle (not doing anything)
270 <failed>0</failed> -- ... Connection failed
271 <error>0</error> -- ... Error was produced somewhere
277 <refsect2 id="command-show">
280 Shows records retrieved. Parameters:
294 <para>First record to show - 0-indexed.</para>
302 Number of records to show If omitted, 20 is used.
311 If block is set to 1, the command will hang until there are records ready
312 to display. Use this to show first records rapidly without
313 requiring rapid polling.
322 Specifies sort criteria. The argument is a comma-separated list
323 (no whitespace allowed) of sort fields, with the highest-priority
324 field first. A sort field may be followed by a colon followed by
325 the number '0' or '1', indicating whether results should be sorted in
326 increasing or decreasing order according to that field. 0==Decreasing is
327 the default. Sort field names can be any field name designated as a sort field
328 in the pazpar2.cfg file, or the special name 'relevance'.
338 search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
344 <activeclients>3</activeclients> -- How many clients are still working
345 <merged>6</merged> -- Number of merged records
346 <total>7</total> -- Total of all hitcounts
347 <start>0</start> -- The start number you requested
348 <num>2</num> -- Number of records retrieved
350 <md-title>How to program a computer, by Jack Collins</md-title>
351 <count>2</count> -- Number of merged records
352 <recid>6</recid> -- Record ID for this record
356 Computer processing of dynamic images from an Anger scintillation camera :
357 the proceedings of a workshop /
366 <refsect2 id="command-record">
367 <title>record</title>
369 Retrieves a detailed record. Unlike the
370 <link linkend="command-show">show</link> command, this command
371 returns metadata records before merging takes place. Parameters:
387 record ID as provided by the
388 <link linkend="command-show">show</link> command.
397 This optional parameter is an integer which, when given, makes
398 Pazpar2 return the raw record for a target. The raw record
399 from first target is numbered 0, second numbered 1, etc.
400 When a raw record is returned Pazpar2 will XSLT transform the
401 record but an XML version is returned. All ISO2709 records are
402 returned as MARCXML. OPAC records are returned as YAZ'
403 OPAC with an MARCXML sibling.
406 When offset is not given the Pazpar2 metadata for the record
407 is returned and with metadata for each targets' data specified
408 in a 'location' list.
417 This optional parameter is the record syntax used for raw
418 transfer (i.e. when offset is specified). If syntax is not given,
419 but offset is used, the value of pz:requestsyntax is used.
428 This optional parameter is the element set name used to retrieval
429 of a raw record (i.e. when offset is specified).
430 If esn is not given, but offset is used, the value of pz:elements
440 This optional parameter enables "binary" response for retrieval
441 of a raw record (i.e. when offset is specified). For binary
442 responses the record is <emphasis>not</emphasis> converted to
443 XML and the HTTP content type is application/octet-stream.
453 search.pz2?session=605047297&command=record&id=3
461 The Puget Sound Region : a portfolio of thematic computer maps /
463 <md-date>1974</md-date>
464 <md-author>Mairs, John W.</md-author>
465 <md-subject>Cartography</md-subject>
471 <refsect2 id="command-termlist">
472 <title>termlist</title>
474 Retrieves term list(s). Parameters:
489 comma-separated list of termlist names (default "subject")
497 maximum number of entries to return - default is 15.
506 search.pz2?session=2044502273&command=termlist&name=author,subject
511 <activeclients>3</activeclients>
514 <name>Donald Knuth</name>
515 <frequency>10</frequency>
518 <name>Robert Pirsig</name>
519 <frequency>2</frequency>
522 <list name="subject">
524 <name>Computer programming</name>
525 <frequency>10</frequency>
533 For the special termlist name "xtargets", results
534 are returned about the targets which have returned the most hits.
535 The 'term' subtree has additional elements,
536 specifically a state and diagnostic field (in the example below, a
537 target ID is returned in place of 'name'.
538 This may or may not change later.
544 <name>library2.mcmaster.ca</name>
545 <frequency>11734</frequency> -- Number of hits
546 <state>Client_Idle</state> -- See the description of 'bytarget' below
547 <diagnostic>0</diagnostic> -- Z39.50 diagnostic codes
554 <refsect2 id="command-bytarget">
555 <title>bytarget</title>
557 Returns information about the status of each active client. Parameters:
573 search.pz2?session=605047297&command=bytarget&id=3
582 <id>z3950.loc.gov/voyager/</id>
584 <diagnostic>0</diagnostic>
585 <records>65</records>
586 <state>Client_Presenting</state>
588 <!-- ... more target nodes below as necessary -->
592 The following client states are defined: Client_Connecting,
593 Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
594 Client_Searching, Client_Presenting, Client_Error, Client_Failed,
595 Client_Disconnected, Client_Stopped, Client_Continue.
600 <refsect1><title>SEE ALSO</title>
604 <refentrytitle>pazpar2</refentrytitle>
605 <manvolnum>8</manvolnum>
609 Pazpar2 Configuration:
611 <refentrytitle>pazpar2_conf</refentrytitle>
612 <manvolnum>5</manvolnum>
618 <!-- Keep this comment at the end of the file
623 sgml-minimize-attributes:nil
624 sgml-always-quote-attributes:t
627 sgml-parent-document:nil
628 sgml-local-catalogs: nil
629 sgml-namecase-general:t