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.
49 search.pz2?command=init
58 <session>2044502273</session>
62 The init command may take a number of setting parameters, similar to
63 the 'settings' command described below. These settings are immediately
64 applied to the new session. Other parameters for init are:
70 If this is defined and the value is non-zero, the session will
71 not use the predefined databases in the configuration; only those
72 specified in the settings parameters (per session databases).
80 <refsect2 id="command-ping"><title>ping</title>
82 Keeps a session alive. An idle session will time out after one minute.
83 The ping command can be used to keep the session alive absent other
85 It is suggested that any browser client have a simple alarm handler which
86 sends a ping every 50 seconds or so once a session has been initialized.
91 search.pz?command=ping&session=2044502273
102 <refsect2 id="command-settings">
103 <title>settings</title>
105 The settings command applies session-specific settings to one or more
106 databases. A typical function of this is to enable access to
107 restricted resources for registered users, or to set a user- or
108 library-specific username/password to use against a target. Each
109 setting parameter has the form name[target]=value, where name is the
110 name of the setting (e.g. pz:authentication), target is a target ID,
111 or possibly a wildcard, and value is the desired value for the
116 Because the settings command manipulates potentially sensitive
117 information, it is possible to configure Pazpar2 to only allow access
118 to this command from a trusted site -- usually from server-side
119 scripting, which in turn is responsible for authenticating the user,
120 and possibly determining which resources he has access to, etc.
125 As a shortcut, it is also possible to override settings directly in
133 search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
144 <refsect2 id="command-search"><title>search</title>
146 Launches a search, parameters:
179 search.pz2?session=2044502273&command=search&query=computer+science
191 <refsect2 id="command-stat">
194 Provides status information about an ongoing search. Parameters:
211 search.pz2?session=2044502273&command=stat
216 <activeclients>3</activeclients>
217 <hits>7</hits> -- Total hitcount
218 <records>7</records> -- Total number of records fetched in last query
219 <clients>1</clients> -- Total number of associated clients
220 <unconnected>0</unconnected> -- Number of disconnected clients
221 <connecting>0</connecting> -- Number of clients in connecting state
222 <initializing>0</initializing> -- Number of clients initializing
223 <searching>0</searching> -- ... searching
224 <presenting>0</presenting> -- ... presenting
225 <idle>1</idle> -- ... idle (not doing anything)
226 <failed>0</failed> -- ... Connection failed
227 <error>0</error> -- ... Error was produced somewhere
233 <refsect2 id="command-show">
236 Shows records retrieved. Parameters:
250 <para>First record to show - 0-indexed.</para>
258 Number of records to show If omitted, 20 is used.
267 If block is set to 1, the command will hang until there are records ready
268 to display. Use this to show first records rapidly without
269 requiring rapid polling.
278 Specifies sort criteria. The argument is a comma-separated list
279 (no whitespace allowed) of sort fields, with the highest-priority
280 field first. A sort field may be followed by a colon followed by
281 the number '0' or '1', indicating whether results should be sorted in
282 increasing or decreasing order according to that field. 0==Decreasing is
293 search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
299 <activeclients>3</activeclients> -- How many clients are still working
300 <merged>6</merged> -- Number of merged records
301 <total>7</total> -- Total of all hitcounts
302 <start>0</start> -- The start number you requested
303 <num>2</num> -- Number of records retrieved
305 <md-title>How to program a computer, by Jack Collins</md-title>
306 <count>2</count> -- Number of merged records
307 <recid>6</recid> -- Record ID for this record
311 Computer processing of dynamic images from an Anger scintillation camera :
312 the proceedings of a workshop /
321 <refsect2 id="command-record">
322 <title>record</title>
324 Retrieves a detailed record. Unlike the
325 <link linkend="command-show">show</link> command, this command
326 returns metadata records before merging takes place. Parameters:
342 record ID as provided by the
343 <link linkend="command-show">show</link> command.
352 This optional parameter is an integer which, when given, makes
353 Pazpar2 return the raw record for a target. The raw record
354 from first target is numbered 0, second numbered 1, etc.
355 When a raw record is returned Pazpar2 will XSLT transform the
356 record but an XML version is returned. All ISO2709 records are
357 returned as MARCXML. OPAC records are returned as YAZ'
358 OPAC with an MARCXML sibling.
361 When offset is not given the Pazpar2 metadata for the record
362 is returned and with metadata for each targets' data specified
363 in a 'location' list.
372 This optional parameter is the record syntax used for raw
373 transfer (i.e. when offset is specified). If syntax is not given,
374 but offset is used, the value of pz:requestsyntax is used.
383 This optional parameter is the element set name used to retrieval
384 of a raw record (i.e. when offset is specified).
385 If esn is not given, but offset is used, the value of pz:elements
395 This optional parameter enables "binary" response for retrieval
396 of a raw record (i.e. when offset is specified). For binary
397 responses the record is <emphasis>not</emphasis> converted to
398 XML and the HTTP content type is application/octet-stream.
408 search.pz2?session=605047297&command=record&id=3
416 The Puget Sound Region : a portfolio of thematic computer maps /
418 <md-date>1974</md-date>
419 <md-author>Mairs, John W.</md-author>
420 <md-subject>Cartography</md-subject>
426 <refsect2 id="command-termlist">
427 <title>termlist</title>
429 Retrieves term list(s). Parameters:
444 comma-separated list of termlist names (default "subject")
453 search.pz2?session=2044502273&command=termlist&name=author,subject
458 <activeclients>3</activeclients>
461 <name>Donald Knuth</name>
462 <frequency>10</frequency>
465 <name>Robert Pirsig</name>
466 <frequency>2</frequency>
469 <list name="subject">
471 <name>Computer programming</name>
472 <frequency>10</frequency>
480 For the special termlist name "xtargets", results
481 are returned about the targets which have returned the most hits.
482 The 'term' subtree has additional elements,
483 specifically a state and diagnostic field (in the example below, a
484 target ID is returned in place of 'name'.
485 This may or may not change later.
491 <name>library2.mcmaster.ca</name>
492 <frequency>11734</frequency> -- Number of hits
493 <state>Client_Idle</state> -- See the description of 'bytarget' below
494 <diagnostic>0</diagnostic> -- Z39.50 diagnostic codes
501 <refsect2 id="command-bytarget">
502 <title>bytarget</title>
504 Returns information about the status of each active client. Parameters:
520 search.pz2?session=605047297&command=bytarget&id=3
529 <id>z3950.loc.gov/voyager/</id>
531 <diagnostic>0</diagnostic>
532 <records>65</records>
533 <state>Client_Presenting</state>
535 <!-- ... more target nodes below as necessary -->
539 The following client states are defined: Client_Connecting,
540 Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
541 Client_Searching, Client_Presenting, Client_Error, Client_Failed,
542 Client_Disconnected, Client_Stopped, Client_Continue.
547 <refsect1><title>SEE ALSO</title>
551 <refentrytitle>pazpar2</refentrytitle>
552 <manvolnum>8</manvolnum>
556 Pazpar2 Configuration:
558 <refentrytitle>pazpar2_conf</refentrytitle>
559 <manvolnum>5</manvolnum>
565 <!-- Keep this comment at the end of the file
570 sgml-minimize-attributes:nil
571 sgml-always-quote-attributes:t
574 sgml-parent-document:nil
575 sgml-local-catalogs: nil
576 sgml-namecase-general:t