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
51 that is included in the session ID as suffix after a period (.).
54 If the init command is performed as a HTTP GET request, service
55 and settings from local files are used. The service parameter
56 may chose a particular local service.
59 If the init command is performed as a HTTP POST request and
60 the content-type is text/xml, then the content is XML parsed
61 and treated as service for the session. The root element should be
62 service. Refer to descripton of the
63 <link linkend="service_conf">service</link> format.
64 The posting of a service appeared in Pazpar2 version 1.2.1.
69 search.pz2?command=init
78 <session>2044502273</session>
82 The init command may take a number of setting parameters, similar to
83 the 'settings' command described below. These settings are immediately
84 applied to the new session. Other parameters for init are:
90 If this is defined and the value is non-zero, the session will
91 not use the predefined databases in the configuration; only those
92 specified in the settings parameters (per session databases).
101 If this is defined it specifies a service ID. Makes the session use
102 the service with this ID. If this is setting is omitted, the
103 session will use the unnamed service in the Pazpar2 configuration.
111 <refsect2 id="command-ping">
114 Keeps a session alive. An idle session will time out after one minute.
115 The ping command can be used to keep the session alive absent other
117 It is suggested that any browser client have a simple alarm handler which
118 sends a ping every 50 seconds or so once a session has been initialized.
123 search.pz?command=ping&session=2044502273
134 <refsect2 id="command-settings">
135 <title>settings</title>
137 The settings command applies session-specific settings to one or more
138 databases. A typical function of this is to enable access to
139 restricted resources for registered users, or to set a user- or
140 library-specific username/password to use against a target.
143 Each setting parameter has the form name[target]=value, where name is the
144 name of the setting (e.g. pz:authentication), target is a target ID,
145 or possibly a wildcard, and value is the desired value for the
150 Because the settings command manipulates potentially sensitive
151 information, it is possible to configure Pazpar2 to only allow access
152 to this command from a trusted site -- usually from server-side
153 scripting, which in turn is responsible for authenticating the user,
154 and possibly determining which resources he has access to, etc.
159 As a shortcut, it is also possible to override settings directly in
165 If the settings command is performed as HTTP POST and the content-type
166 is text/xml, then the content is XML parsed and treated as settings -
167 with a format identical to local
168 <link linkend="target_settings">settings files</link>.
169 The posting of settings appeared in Pazpar version 1.2.1.
175 search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
186 <refsect2 id="command-search">
187 <title>search</title>
189 Launches a search, parameters:
212 Limits the search to a given set of targets specified by the
213 filter. The filter consists of a comma separated list of
214 <emphasis>setting</emphasis>+<emphasis>operator</emphasis>+<emphasis>args</emphasis>
215 pairs. The <emphasis>setting</emphasis> is a Pazpar2 setting
216 (such as <literal>pz:id</literal>).
217 The <emphasis>operator</emphasis> is either
218 <literal>=</literal> (string match)
219 or <literal>~</literal> (substring match).
220 The <emphasis>args</emphasis> is a list of values separated
221 by <literal>|</literal> (or , one of the values).
222 The idea is that only targets with a setting matching one of
223 the values given will be included in the search.
231 Narrows the search by one or more fields (typically facets).
232 The limit is sequence of one or more
233 <emphasis>name</emphasis>=<emphasis>args</emphasis> pairs separated
234 by comma. The <emphasis>args</emphasis> is a list of values
235 separated by vertical bar (<literal>|</literal>).
236 The meaning of <literal>|</literal> is alternative, ie OR .
237 A value that contains a comma (<literal>,</literal>),
238 a vertical bar (<literal>|</literal>) or
239 backslash itself must be preceded by backslash (<literal>\</literal>).
240 The <link linkend="limitmap">pz:limitmap</link> configuration
241 item defines how the searches are mapped to a database.
246 <term>startrecs</term>
249 Specifies the first record to retrieve from each target.
250 The first record in a result set for a target is numbered 0, next
251 record is numbered 1. By default startrecs is 0.
259 Specifies the maximum number of records to retrieve from each
260 target. The default value is 100. This setting has same meaning
261 as per-target setting pz:maxrecs . If pz:maxrecs is set, it takes
262 precedence over argument maxrecs.
270 Specifies sort criteria. The argument is a comma-separated list
271 (no whitespace allowed) of sort fields, with the highest-priority
272 field first. A sort field may be followed by a colon followed by
273 the number '0' (decreasing) or '1' (increasing). Default
274 sort order is decreasing.
275 Sort field names can be any field name designated as a sort field
276 in the pazpar2.cfg file, or the special names 'relevance',
277 'retrieval' and 'position'.
280 Sort type 'position' sorts by position/offset for each database.
281 Sort type 'retrieval' sorts by position of retrieval (first record
282 retrieved is 1, second record is 2, etc.).
285 If not specified here or as
286 <link linkend="sort-default">sort-default"</link>
287 in pazpar2.cfg, Pazpar2 will default to the built-in
291 Having sort criteria at search is important for targets that
292 supports native sorting in order to get best results. Pazpar2
293 will trigger a new search if search criteria changes from Pazpar2
294 to target-based sorting or visa-versa.
300 <term>mergekey</term>
303 Sets mergekey for this search and rest of session, or until
304 another mergekey is given for show/search. The mergekey value is a
305 comma separated list with one or more names as they appear
306 in the service description equivalent to
307 <literal>mergekey="optional"</literal> inside a metadata element.
308 If the empty string is given for mergekey it is disabled
309 and rest of session will use the default mergekey from service
313 This facility, "dynamic mergekey", appeared in Pazpar2 version
323 Sets rank method this search and rest of session, or until
324 another rank is given for show/search. The rank value is a
325 comma separated list of pairs field=value pairs. The
326 format is the same as
327 <xref linkend="metadata-rank">rank</xref> for a metadata element.
328 If the empty string is given for rank it is disabled
329 and rest of session will use the default rank from metadata or
333 This facility, "dynamic ranking", appeared in Pazpar2 version
345 search.pz2?session=2044502273&command=search&query=computer+science
357 <refsect2 id="command-stat">
360 Provides status information about an ongoing search. Parameters:
377 search.pz2?session=2044502273&command=stat
382 <activeclients>3</activeclients>
383 <hits>7</hits> -- Total hitcount
384 <records>7</records> -- Total number of records fetched in last query
385 <clients>1</clients> -- Total number of associated clients
386 <unconnected>0</unconnected> -- Number of disconnected clients
387 <connecting>0</connecting> -- Number of clients in connecting state
388 <initializing>0</initializing> -- Number of clients initializing
389 <searching>0</searching> -- ... searching
390 <presenting>0</presenting> -- ... presenting
391 <idle>1</idle> -- ... idle (not doing anything)
392 <failed>0</failed> -- ... Connection failed
393 <error>0</error> -- ... Error was produced somewhere
399 <refsect2 id="command-show">
402 Shows records retrieved. Parameters:
416 <para>First record to show - 0-indexed.</para>
424 Number of records to show If omitted, 20 is used.
433 If block is set to 1, the command will hang until there are records
434 ready to display. Use this to show first records rapidly without
435 requiring rapid polling.
438 If block is set to <literal>preferred</literal>, the command will
439 wait until records have been received from all databases with preferred
449 Specifies sort criteria. The argument is a comma-separated list
450 (no whitespace allowed) of sort fields, with the highest-priority
451 field first. A sort field may be followed by a colon followed by
452 the number '0' (decreasing) or '1' (increasing). Default
453 sort order is decreasing.
454 Sort field names can be any field name designated as a sort field
455 in the pazpar2.cfg file, or the special names 'relevance',
456 'retrieval' and 'position'.
459 Sort type 'position' sorts by position/offset for each database.
460 Sort type 'retrieval' sorts by position of retrieval (first record
461 retrieved is 1, second record is 2, etc.).
464 If not specified here or as
465 <link linkend="sort-default">sort-default"</link>
466 in pazpar2.cfg, pazpar2 will default to the built-in
470 Having sort criteria at search is important for targets that
471 supports native sorting in order to get best results. pazpar2
472 will trigger a new search if search criteria changes from pazpar2
473 to target-based sorting.
476 For targets where If <link linkend="pzsortmap">pz:sortmap</link>
477 is defined, a sort operation will be executed (possibly including
478 extending the search).
484 <term>mergekey</term>
487 Sets mergekey for this show and rest of session, or until
488 another mergekey is given for show/search. The mergekey value is a
489 comma separated list with one or more names as they appear
490 in the service description equivalent to
491 <literal>mergekey="optional"</literal> inside a metadata element.
492 If the empty string is given for mergekey it is disabled
493 and rest of session will use the default mergekey from service
497 This facility, "dynamic mergekey", appeared in Pazpar2 version
507 Sets rank method this show and rest of session, or until
508 another rank is given for show/search. The rank value is a
509 comma separated list of pairs field=value pairs. The
510 format is the same as
511 <xref linkend="metadata-rank">rank</xref> for a metadata element.
512 If the empty string is given for rank it is disabled
513 and rest of session will use the default rank from metadata or
517 This facility, "dynamic ranking", appeared in Pazpar2 version
524 <term>snippets</term>
527 If specified and set to 1 data will include snippets marked
528 with <match> tags. Otherwise snippets will not be included.
531 This facility, "snippets", appeared in Pazpar2 version
542 search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
548 <activeclients>3</activeclients> -- How many clients are still working
549 <merged>6</merged> -- Number of merged records
550 <total>7</total> -- Total of all hitcounts
551 <start>0</start> -- The start number you requested
552 <num>2</num> -- Number of records retrieved
554 <md-title>How to program a computer, by Jack Collins</md-title>
555 <count>2</count> -- Number of merged records
556 <recid>6</recid> -- Record ID for this record
560 Computer processing of dynamic images from an Anger scintillation camera :
561 the proceedings of a workshop /
570 <refsect2 id="command-record">
571 <title>record</title>
573 Retrieves a detailed record. Unlike the
574 <link linkend="command-show">show</link> command, this command
575 returns metadata records before merging takes place. Parameters:
591 record ID as provided by the
592 <link linkend="command-show">show</link> command.
601 This optional parameter is an integer which, when given, makes
602 Pazpar2 return the original record for a specific target.
603 The record set from first target is numbered 0,
604 second record set is numbered 1, etc.
605 The nativesyntax setting, as usual, is used to determine how to
606 create XML from the original record - unless parameter
607 <literal>binary</literal> is given in which the record is
608 fetched as "raw" from ZOOM C (raw, original record).
611 When offset/checksum is not given, the Pazpar2 metadata for the record
612 is returned and with metadata for each targets' data specified
613 in a 'location' list.
619 <term>checksum</term>
622 This optional parameter is a string which, when given, makes
623 Pazpar2 return the original record for a specific target. The
624 checksum is returned as attribtue 'checksum' in element
625 'location' for show command and record command (when checksum
626 and offset is NOT given).
627 The nativesyntax setting, as usual, is used to determine how to
628 create XML from the original record - unless parameter
629 <literal>binary</literal> is given in which the record is
630 fetched as "raw" from ZOOM C (raw, original record).
633 When offset/checksum is not given, the Pazpar2 metadata for the record
634 is returned and with metadata for each targets' data specified
635 in a 'location' list.
642 <term>nativesyntax</term>
645 This optional parameter can be used to override pz:nativesyntax
646 as given for the target. This allow an alternative nativesyntax
647 to be used for original records (see parameteroffset above).
656 This optional parameter is the record syntax used for raw
657 transfer (i.e. when offset is specified). If syntax is not given,
658 but offset is used, the value of pz:requestsyntax is used.
667 This optional parameter is the element set name used to retrieval
668 of a raw record (i.e. when offset is specified).
669 If esn is not given, but offset is used, the value of pz:elements
679 This optional parameter enables "binary" response for retrieval
680 of a original record (i.e. when offset is specified). For binary
681 response the record by default is fetched from ZOOM C using
682 the "raw" option or by parameter nativesyntax if given.
688 <term>snippets</term>
691 If specified and set to 1 data will include snippets marked
692 with <match> tags. Otherwise snippets will not be included.
695 This facility, "snippets", appeared in Pazpar2 version
706 search.pz2?session=605047297&command=record&id=3
714 The Puget Sound Region : a portfolio of thematic computer maps /
716 <md-date>1974</md-date>
717 <md-author>Mairs, John W.</md-author>
718 <md-subject>Cartography</md-subject>
724 <refsect2 id="command-stop">
727 Makes Pazpar2 stop further search & retrieval for busy databases.
731 <refsect2 id="command-termlist">
732 <title>termlist</title>
734 Retrieves term list(s). Parameters:
749 comma-separated list of termlist names. If omitted,
750 all termlists are returned.
758 maximum number of entries to return - default is 15.
767 search.pz2?session=2044502273&command=termlist&name=author,subject
772 <activeclients>3</activeclients>
775 <name>Donald Knuth</name>
776 <frequency>10</frequency>
779 <name>Robert Pirsig</name>
780 <frequency>2</frequency>
783 <list name="subject">
785 <name>Computer programming</name>
786 <frequency>10</frequency>
794 For the special termlist name "xtargets", results
795 are returned about the targets which have returned the most hits.
796 The 'term' subtree has additional elements,
797 specifically a state and diagnostic field (in the example below, a
798 target ID is returned in place of 'name'.
799 This may or may not change later.
805 <name>library2.mcmaster.ca</name>
806 <frequency>11734</frequency> -- Number of hits
807 <state>Client_Idle</state> -- See the description of 'bytarget' below
808 <diagnostic>0</diagnostic> -- Z39.50 diagnostic codes
815 <refsect2 id="command-bytarget">
816 <title>bytarget</title>
818 Returns information about the status of each active client. Parameters:
834 search.pz2?session=605047297&command=bytarget&id=3
843 <id>z3950.loc.gov/voyager/</id>
845 <diagnostic>0</diagnostic>
846 <records>65</records>
847 <state>Client_Presenting</state>
849 <!-- ... more target nodes below as necessary -->
853 The following client states are defined: Client_Connecting,
854 Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
855 Client_Searching, Client_Presenting, Client_Error, Client_Failed,
856 Client_Disconnected, Client_Stopped, Client_Continue.
860 <refsect2 id="command-service">
861 <title>service</title>
863 Returns service definition (XML). Parameters:
876 The service command appeared in Pazpar2 version 1.6.32
881 <title>SEE ALSO</title>
885 <refentrytitle>pazpar2</refentrytitle>
886 <manvolnum>8</manvolnum>
890 Pazpar2 Configuration:
892 <refentrytitle>pazpar2_conf</refentrytitle>
893 <manvolnum>5</manvolnum>
899 <!-- Keep this comment at the end of the file