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>
30 <title>DESCRIPTION</title>
32 Webservice requests are any that refer to filename "search.pz2". Arguments
33 are GET-style parameters. Argument 'command' is always required and specifies
34 the operation to perform. Any request not recognized as a webservice
35 request is forwarded to the HTTP server specified in the configuration
36 using the proxy setting.
37 This way, a regular webserver can host the user interface (itself dynamic
38 or static HTML), and Ajax-style calls can be used from JS (or any other
39 client-based scripting environment) to interact with the search logic
43 Each command is described in sub sections to follow.
45 <refsect2 id="command-init">
48 Initializes a session.
49 Returns session ID to be used in subsequent requests. If
50 a server ID is given in the Pazpar2 server section, then a
51 period (.) and the server ID is appended to the session ID.
56 search.pz2?command=init
65 <session>2044502273</session>
69 The init command may take a number of setting parameters, similar to
70 the 'settings' command described below. These settings are immediately
71 applied to the new session. Other parameters for init are:
77 If this is defined and the value is non-zero, the session will
78 not use the predefined databases in the configuration; only those
79 specified in the settings parameters (per session databases).
88 If this is defined it specifies a service ID. Makes the session use
89 the service with this ID. If this is setting is omitted, the
90 session will use the unnamed service in the Pazpar2 configuration.
98 <refsect2 id="command-ping">
101 Keeps a session alive. An idle session will time out after one minute.
102 The ping command can be used to keep the session alive absent other
104 It is suggested that any browser client have a simple alarm handler which
105 sends a ping every 50 seconds or so once a session has been initialized.
110 search.pz?command=ping&session=2044502273
121 <refsect2 id="command-settings">
122 <title>settings</title>
124 The settings command applies session-specific settings to one or more
125 databases. A typical function of this is to enable access to
126 restricted resources for registered users, or to set a user- or
127 library-specific username/password to use against a target. Each
128 setting parameter has the form name[target]=value, where name is the
129 name of the setting (e.g. pz:authentication), target is a target ID,
130 or possibly a wildcard, and value is the desired value for the
135 Because the settings command manipulates potentially sensitive
136 information, it is possible to configure Pazpar2 to only allow access
137 to this command from a trusted site -- usually from server-side
138 scripting, which in turn is responsible for authenticating the user,
139 and possibly determining which resources he has access to, etc.
144 As a shortcut, it is also possible to override settings directly in
152 search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
163 <refsect2 id="command-search">
164 <title>search</title>
166 Launches a search, parameters:
189 Limits the search to a given set of targets specified by the
190 filter. The filter consists a comma separated list of
191 <emphasis>setting</emphasis>+<emphasis>operator</emphasis>+<emphasis>args</emphasis>
192 pairs. The <emphasis>setting</emphasis> is a Pazpar2 setting
193 (such as <literal>pz:id</literal>).
194 The <emphasis>operator</emphasis> is either
195 <literal>=</literal> (string match)
196 or <literal>~</literal> (substring match).
197 The <emphasis>args</emphasis> is a list of values separated
198 by <literal>|</literal> (or , one of the values).
199 The idea is that only targets with a setting matching one of
200 the values given will be included in the search.
208 Narrows the search by one or more fields (typically facets).
209 The limit is sequence of one or more
210 <emphasis>name</emphasis>=<emphasis>args</emphasis> pairs separated
211 by comma. The <emphasis>args</emphasis> is a list of values
212 separated by vertical bar (<literal>|</literal>).
213 The meaning of <literal>|</literal> is alternative, ie OR .
214 A value that contains a comma (<literal>,</literal>),
215 a vertical bar (<literal>|</literal>) or
216 backslash itself must be preceded by backslash (<literal>\</literal>).
217 The <link linkend="limitmap">pz:limitmap</link> configuration
218 item defines how the searches are mapped to a database.
223 <term>startrecs</term>
226 Specifies the first record to retrieve from each target.
227 The first record in a result set for a target is numbered 0, next
228 record is numbered 2. By default maxrecs is 0.
236 Specifies the maximum number of records to retrieve from each
237 target. The default value is 100. This setting has same meaning
238 as per-target setting pz:maxrecs . If pz:maxrecs is set, it takes
239 precedence over argument maxrecs.
247 Specifies sort criteria. The argument is a comma-separated list
248 (no whitespace allowed) of sort fields, with the highest-priority
249 field first. A sort field may be followed by a colon followed by
250 the number '0' (decreasing) or '1' (increasing). Default
251 sort order is decreasing.
252 Sort field names can be any field name designated as a sort field
253 in the pazpar2.cfg file, or the special names 'relevance' and
257 If not specified here or as <link linkend="sort-default">sort-default"</link>
258 in pazpar2.cfg, Pazpar2 will default to the built-in 'relevance' ranking.
261 Having sort criteria at search is important for targets that
262 supports native sorting in order to get best results. Pazpar2
263 will trigger a new search if search criteria changes from Pazpar2
264 to target-based sorting or visa-versa.
274 search.pz2?session=2044502273&command=search&query=computer+science
286 <refsect2 id="command-stat">
289 Provides status information about an ongoing search. Parameters:
306 search.pz2?session=2044502273&command=stat
311 <activeclients>3</activeclients>
312 <hits>7</hits> -- Total hitcount
313 <records>7</records> -- Total number of records fetched in last query
314 <clients>1</clients> -- Total number of associated clients
315 <unconnected>0</unconnected> -- Number of disconnected clients
316 <connecting>0</connecting> -- Number of clients in connecting state
317 <initializing>0</initializing> -- Number of clients initializing
318 <searching>0</searching> -- ... searching
319 <presenting>0</presenting> -- ... presenting
320 <idle>1</idle> -- ... idle (not doing anything)
321 <failed>0</failed> -- ... Connection failed
322 <error>0</error> -- ... Error was produced somewhere
328 <refsect2 id="command-show">
331 Shows records retrieved. Parameters:
345 <para>First record to show - 0-indexed.</para>
353 Number of records to show If omitted, 20 is used.
362 If block is set to 1, the command will hang until there are records
363 ready to display. Use this to show first records rapidly without
364 requiring rapid polling.
373 Specifies sort criteria. The argument is a comma-separated list
374 (no whitespace allowed) of sort fields, with the highest-priority
375 field first. A sort field may be followed by a colon followed by
376 the number '0' (decreasing) or '1' (increasing). Default
377 sort order is decreasing.
378 Sort field names can be any field name designated as a sort field
379 in the pazpar2.cfg file, or the special names 'relevance' and
382 If not specified here or as <link linkend="sort-default">sort-default"</link>
383 in pazpar2.cfg, pazpar2 will default to the built-in 'relevance' ranking.
385 Having sort criteria at search is important for targets that
386 supports native sorting in order to get best results. pazpar2
387 will trigger a new search if search criteria changes from pazpar2
388 to target-based sorting.
392 For targets where If <link linkend="pz:sortmap">pz:sortmap</link>
393 is defined, a sort operation will be executed (possibly including
394 extending the search).
404 search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
410 <activeclients>3</activeclients> -- How many clients are still working
411 <merged>6</merged> -- Number of merged records
412 <total>7</total> -- Total of all hitcounts
413 <start>0</start> -- The start number you requested
414 <num>2</num> -- Number of records retrieved
416 <md-title>How to program a computer, by Jack Collins</md-title>
417 <count>2</count> -- Number of merged records
418 <recid>6</recid> -- Record ID for this record
422 Computer processing of dynamic images from an Anger scintillation camera :
423 the proceedings of a workshop /
432 <refsect2 id="command-record">
433 <title>record</title>
435 Retrieves a detailed record. Unlike the
436 <link linkend="command-show">show</link> command, this command
437 returns metadata records before merging takes place. Parameters:
453 record ID as provided by the
454 <link linkend="command-show">show</link> command.
463 This optional parameter is an integer which, when given, makes
464 Pazpar2 return the original record for a specific target.
465 The record set from first target is numbered 0,
466 second record set is numbered 1, etc.
467 The nativesyntax setting, as usual, is used to determine how to
468 create XML from the original record - unless parameter
469 <literal>binary</literal> is given in which the record is
470 fetched as "raw" from ZOOM C (raw, original record).
473 When offset/checksum is not given, the Pazpar2 metadata for the record
474 is returned and with metadata for each targets' data specified
475 in a 'location' list.
481 <term>checksum</term>
484 This optional parameter is a string which, when given, makes
485 Pazpar2 return the original record for a specific target. The
486 checksum is returned as attribtue 'checksum' in element
487 'location' for show command and record command (when checksum
488 and offset is NOT given).
489 The nativesyntax setting, as usual, is used to determine how to
490 create XML from the original record - unless parameter
491 <literal>binary</literal> is given in which the record is
492 fetched as "raw" from ZOOM C (raw, original record).
495 When offset/checksum is not given, the Pazpar2 metadata for the record
496 is returned and with metadata for each targets' data specified
497 in a 'location' list.
504 <term>nativesyntax</term>
507 This optional parameter can be used to override pz:nativesyntax
508 as given for the target. This allow an alternative nativesyntax
509 to be used for original records (see parameteroffset above).
518 This optional parameter is the record syntax used for raw
519 transfer (i.e. when offset is specified). If syntax is not given,
520 but offset is used, the value of pz:requestsyntax is used.
529 This optional parameter is the element set name used to retrieval
530 of a raw record (i.e. when offset is specified).
531 If esn is not given, but offset is used, the value of pz:elements
541 This optional parameter enables "binary" response for retrieval
542 of a original record (i.e. when offset is specified). For binary
543 response the record by default is fetched from ZOOM C using
544 the "raw" option or by parameter nativesyntax if given.
554 search.pz2?session=605047297&command=record&id=3
562 The Puget Sound Region : a portfolio of thematic computer maps /
564 <md-date>1974</md-date>
565 <md-author>Mairs, John W.</md-author>
566 <md-subject>Cartography</md-subject>
572 <refsect2 id="command-termlist">
573 <title>termlist</title>
575 Retrieves term list(s). Parameters:
590 comma-separated list of termlist names. If omitted,
591 all termlists are returned.
599 maximum number of entries to return - default is 15.
608 search.pz2?session=2044502273&command=termlist&name=author,subject
613 <activeclients>3</activeclients>
616 <name>Donald Knuth</name>
617 <frequency>10</frequency>
620 <name>Robert Pirsig</name>
621 <frequency>2</frequency>
624 <list name="subject">
626 <name>Computer programming</name>
627 <frequency>10</frequency>
635 For the special termlist name "xtargets", results
636 are returned about the targets which have returned the most hits.
637 The 'term' subtree has additional elements,
638 specifically a state and diagnostic field (in the example below, a
639 target ID is returned in place of 'name'.
640 This may or may not change later.
646 <name>library2.mcmaster.ca</name>
647 <frequency>11734</frequency> -- Number of hits
648 <state>Client_Idle</state> -- See the description of 'bytarget' below
649 <diagnostic>0</diagnostic> -- Z39.50 diagnostic codes
656 <refsect2 id="command-bytarget">
657 <title>bytarget</title>
659 Returns information about the status of each active client. Parameters:
675 search.pz2?session=605047297&command=bytarget&id=3
684 <id>z3950.loc.gov/voyager/</id>
686 <diagnostic>0</diagnostic>
687 <records>65</records>
688 <state>Client_Presenting</state>
690 <!-- ... more target nodes below as necessary -->
694 The following client states are defined: Client_Connecting,
695 Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
696 Client_Searching, Client_Presenting, Client_Error, Client_Failed,
697 Client_Disconnected, Client_Stopped, Client_Continue.
703 <title>SEE ALSO</title>
707 <refentrytitle>pazpar2</refentrytitle>
708 <manvolnum>8</manvolnum>
712 Pazpar2 Configuration:
714 <refentrytitle>pazpar2_conf</refentrytitle>
715 <manvolnum>5</manvolnum>
721 <!-- Keep this comment at the end of the file