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
200 Narrows the search by one or more fields (typicall facets).
201 The limit is sequence of one or more field=value pairs separate
203 A value that contains a comma should be escaped by backslash (\).
204 The pz:fazetmap configuration item defines how the searches are
205 mapped to a database.
210 <term>startrecs</term>
213 Specifies the first record to retrieve from each target.
214 The first record in a result set for a target is numbered 0, next
215 record is numbered 2. By default maxrecs is 0.
223 Specifies the maximum number of records to retrieve from each
224 target. The default value is 100. This setting has same meaning
225 as per-target setting pz:maxrecs . If pz:maxrecs is set, it takes
226 precedence over argument maxrecs.
236 search.pz2?session=2044502273&command=search&query=computer+science
248 <refsect2 id="command-stat">
251 Provides status information about an ongoing search. Parameters:
268 search.pz2?session=2044502273&command=stat
273 <activeclients>3</activeclients>
274 <hits>7</hits> -- Total hitcount
275 <records>7</records> -- Total number of records fetched in last query
276 <clients>1</clients> -- Total number of associated clients
277 <unconnected>0</unconnected> -- Number of disconnected clients
278 <connecting>0</connecting> -- Number of clients in connecting state
279 <initializing>0</initializing> -- Number of clients initializing
280 <searching>0</searching> -- ... searching
281 <presenting>0</presenting> -- ... presenting
282 <idle>1</idle> -- ... idle (not doing anything)
283 <failed>0</failed> -- ... Connection failed
284 <error>0</error> -- ... Error was produced somewhere
290 <refsect2 id="command-show">
293 Shows records retrieved. Parameters:
307 <para>First record to show - 0-indexed.</para>
315 Number of records to show If omitted, 20 is used.
324 If block is set to 1, the command will hang until there are records ready
325 to display. Use this to show first records rapidly without
326 requiring rapid polling.
335 Specifies sort criteria. The argument is a comma-separated list
336 (no whitespace allowed) of sort fields, with the highest-priority
337 field first. A sort field may be followed by a colon followed by
338 the number '0' or '1', indicating whether results should be sorted in
339 increasing or decreasing order according to that field. 0==Decreasing is
340 the default. Sort field names can be any field name designated as a sort field
341 in the pazpar2.cfg file, or the special name 'relevance'.
351 search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
357 <activeclients>3</activeclients> -- How many clients are still working
358 <merged>6</merged> -- Number of merged records
359 <total>7</total> -- Total of all hitcounts
360 <start>0</start> -- The start number you requested
361 <num>2</num> -- Number of records retrieved
363 <md-title>How to program a computer, by Jack Collins</md-title>
364 <count>2</count> -- Number of merged records
365 <recid>6</recid> -- Record ID for this record
369 Computer processing of dynamic images from an Anger scintillation camera :
370 the proceedings of a workshop /
379 <refsect2 id="command-record">
380 <title>record</title>
382 Retrieves a detailed record. Unlike the
383 <link linkend="command-show">show</link> command, this command
384 returns metadata records before merging takes place. Parameters:
400 record ID as provided by the
401 <link linkend="command-show">show</link> command.
410 This optional parameter is an integer which, when given, makes
411 Pazpar2 return the raw record for a target. The raw record
412 from first target is numbered 0, second numbered 1, etc.
413 When a raw record is returned Pazpar2 will XSLT transform the
414 record but an XML version is returned. All ISO2709 records are
415 returned as MARCXML. OPAC records are returned as YAZ'
416 OPAC with an MARCXML sibling.
419 When offset is not given the Pazpar2 metadata for the record
420 is returned and with metadata for each targets' data specified
421 in a 'location' list.
430 This optional parameter is the record syntax used for raw
431 transfer (i.e. when offset is specified). If syntax is not given,
432 but offset is used, the value of pz:requestsyntax is used.
441 This optional parameter is the element set name used to retrieval
442 of a raw record (i.e. when offset is specified).
443 If esn is not given, but offset is used, the value of pz:elements
453 This optional parameter enables "binary" response for retrieval
454 of a raw record (i.e. when offset is specified). For binary
455 responses the record is <emphasis>not</emphasis> converted to
456 XML and the HTTP content type is application/octet-stream.
466 search.pz2?session=605047297&command=record&id=3
474 The Puget Sound Region : a portfolio of thematic computer maps /
476 <md-date>1974</md-date>
477 <md-author>Mairs, John W.</md-author>
478 <md-subject>Cartography</md-subject>
484 <refsect2 id="command-termlist">
485 <title>termlist</title>
487 Retrieves term list(s). Parameters:
502 comma-separated list of termlist names (default "subject")
510 maximum number of entries to return - default is 15.
519 search.pz2?session=2044502273&command=termlist&name=author,subject
524 <activeclients>3</activeclients>
527 <name>Donald Knuth</name>
528 <frequency>10</frequency>
531 <name>Robert Pirsig</name>
532 <frequency>2</frequency>
535 <list name="subject">
537 <name>Computer programming</name>
538 <frequency>10</frequency>
546 For the special termlist name "xtargets", results
547 are returned about the targets which have returned the most hits.
548 The 'term' subtree has additional elements,
549 specifically a state and diagnostic field (in the example below, a
550 target ID is returned in place of 'name'.
551 This may or may not change later.
557 <name>library2.mcmaster.ca</name>
558 <frequency>11734</frequency> -- Number of hits
559 <state>Client_Idle</state> -- See the description of 'bytarget' below
560 <diagnostic>0</diagnostic> -- Z39.50 diagnostic codes
567 <refsect2 id="command-bytarget">
568 <title>bytarget</title>
570 Returns information about the status of each active client. Parameters:
586 search.pz2?session=605047297&command=bytarget&id=3
595 <id>z3950.loc.gov/voyager/</id>
597 <diagnostic>0</diagnostic>
598 <records>65</records>
599 <state>Client_Presenting</state>
601 <!-- ... more target nodes below as necessary -->
605 The following client states are defined: Client_Connecting,
606 Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
607 Client_Searching, Client_Presenting, Client_Error, Client_Failed,
608 Client_Disconnected, Client_Stopped, Client_Continue.
613 <refsect1><title>SEE ALSO</title>
617 <refentrytitle>pazpar2</refentrytitle>
618 <manvolnum>8</manvolnum>
622 Pazpar2 Configuration:
624 <refentrytitle>pazpar2_conf</refentrytitle>
625 <manvolnum>5</manvolnum>
631 <!-- Keep this comment at the end of the file
636 sgml-minimize-attributes:nil
637 sgml-always-quote-attributes:t
640 sgml-parent-document:nil
641 sgml-local-catalogs: nil
642 sgml-namecase-general:t