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).
81 If this is defined it specifies a service ID. Makes the session use
82 the service with this ID. If this is setting is omitted, the
83 session will use the unnamed service in the Pazpar2 configuration.
91 <refsect2 id="command-ping"><title>ping</title>
93 Keeps a session alive. An idle session will time out after one minute.
94 The ping command can be used to keep the session alive absent other
96 It is suggested that any browser client have a simple alarm handler which
97 sends a ping every 50 seconds or so once a session has been initialized.
102 search.pz?command=ping&session=2044502273
113 <refsect2 id="command-settings">
114 <title>settings</title>
116 The settings command applies session-specific settings to one or more
117 databases. A typical function of this is to enable access to
118 restricted resources for registered users, or to set a user- or
119 library-specific username/password to use against a target. Each
120 setting parameter has the form name[target]=value, where name is the
121 name of the setting (e.g. pz:authentication), target is a target ID,
122 or possibly a wildcard, and value is the desired value for the
127 Because the settings command manipulates potentially sensitive
128 information, it is possible to configure Pazpar2 to only allow access
129 to this command from a trusted site -- usually from server-side
130 scripting, which in turn is responsible for authenticating the user,
131 and possibly determining which resources he has access to, etc.
136 As a shortcut, it is also possible to override settings directly in
144 search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
155 <refsect2 id="command-search"><title>search</title>
157 Launches a search, parameters:
190 search.pz2?session=2044502273&command=search&query=computer+science
202 <refsect2 id="command-stat">
205 Provides status information about an ongoing search. Parameters:
222 search.pz2?session=2044502273&command=stat
227 <activeclients>3</activeclients>
228 <hits>7</hits> -- Total hitcount
229 <records>7</records> -- Total number of records fetched in last query
230 <clients>1</clients> -- Total number of associated clients
231 <unconnected>0</unconnected> -- Number of disconnected clients
232 <connecting>0</connecting> -- Number of clients in connecting state
233 <initializing>0</initializing> -- Number of clients initializing
234 <searching>0</searching> -- ... searching
235 <presenting>0</presenting> -- ... presenting
236 <idle>1</idle> -- ... idle (not doing anything)
237 <failed>0</failed> -- ... Connection failed
238 <error>0</error> -- ... Error was produced somewhere
244 <refsect2 id="command-show">
247 Shows records retrieved. Parameters:
261 <para>First record to show - 0-indexed.</para>
269 Number of records to show If omitted, 20 is used.
278 If block is set to 1, the command will hang until there are records ready
279 to display. Use this to show first records rapidly without
280 requiring rapid polling.
289 Specifies sort criteria. The argument is a comma-separated list
290 (no whitespace allowed) of sort fields, with the highest-priority
291 field first. A sort field may be followed by a colon followed by
292 the number '0' or '1', indicating whether results should be sorted in
293 increasing or decreasing order according to that field. 0==Decreasing is
294 the default. Sort field names can be any field name designated as a sort field
295 in the pazpar2.cfg file, or the special name 'relevance'.
305 search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
311 <activeclients>3</activeclients> -- How many clients are still working
312 <merged>6</merged> -- Number of merged records
313 <total>7</total> -- Total of all hitcounts
314 <start>0</start> -- The start number you requested
315 <num>2</num> -- Number of records retrieved
317 <md-title>How to program a computer, by Jack Collins</md-title>
318 <count>2</count> -- Number of merged records
319 <recid>6</recid> -- Record ID for this record
323 Computer processing of dynamic images from an Anger scintillation camera :
324 the proceedings of a workshop /
333 <refsect2 id="command-record">
334 <title>record</title>
336 Retrieves a detailed record. Unlike the
337 <link linkend="command-show">show</link> command, this command
338 returns metadata records before merging takes place. Parameters:
354 record ID as provided by the
355 <link linkend="command-show">show</link> command.
364 This optional parameter is an integer which, when given, makes
365 Pazpar2 return the raw record for a target. The raw record
366 from first target is numbered 0, second numbered 1, etc.
367 When a raw record is returned Pazpar2 will XSLT transform the
368 record but an XML version is returned. All ISO2709 records are
369 returned as MARCXML. OPAC records are returned as YAZ'
370 OPAC with an MARCXML sibling.
373 When offset is not given the Pazpar2 metadata for the record
374 is returned and with metadata for each targets' data specified
375 in a 'location' list.
384 This optional parameter is the record syntax used for raw
385 transfer (i.e. when offset is specified). If syntax is not given,
386 but offset is used, the value of pz:requestsyntax is used.
395 This optional parameter is the element set name used to retrieval
396 of a raw record (i.e. when offset is specified).
397 If esn is not given, but offset is used, the value of pz:elements
407 This optional parameter enables "binary" response for retrieval
408 of a raw record (i.e. when offset is specified). For binary
409 responses the record is <emphasis>not</emphasis> converted to
410 XML and the HTTP content type is application/octet-stream.
420 search.pz2?session=605047297&command=record&id=3
428 The Puget Sound Region : a portfolio of thematic computer maps /
430 <md-date>1974</md-date>
431 <md-author>Mairs, John W.</md-author>
432 <md-subject>Cartography</md-subject>
438 <refsect2 id="command-termlist">
439 <title>termlist</title>
441 Retrieves term list(s). Parameters:
456 comma-separated list of termlist names (default "subject")
465 search.pz2?session=2044502273&command=termlist&name=author,subject
470 <activeclients>3</activeclients>
473 <name>Donald Knuth</name>
474 <frequency>10</frequency>
477 <name>Robert Pirsig</name>
478 <frequency>2</frequency>
481 <list name="subject">
483 <name>Computer programming</name>
484 <frequency>10</frequency>
492 For the special termlist name "xtargets", results
493 are returned about the targets which have returned the most hits.
494 The 'term' subtree has additional elements,
495 specifically a state and diagnostic field (in the example below, a
496 target ID is returned in place of 'name'.
497 This may or may not change later.
503 <name>library2.mcmaster.ca</name>
504 <frequency>11734</frequency> -- Number of hits
505 <state>Client_Idle</state> -- See the description of 'bytarget' below
506 <diagnostic>0</diagnostic> -- Z39.50 diagnostic codes
513 <refsect2 id="command-bytarget">
514 <title>bytarget</title>
516 Returns information about the status of each active client. Parameters:
532 search.pz2?session=605047297&command=bytarget&id=3
541 <id>z3950.loc.gov/voyager/</id>
543 <diagnostic>0</diagnostic>
544 <records>65</records>
545 <state>Client_Presenting</state>
547 <!-- ... more target nodes below as necessary -->
551 The following client states are defined: Client_Connecting,
552 Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
553 Client_Searching, Client_Presenting, Client_Error, Client_Failed,
554 Client_Disconnected, Client_Stopped, Client_Continue.
559 <refsect1><title>SEE ALSO</title>
563 <refentrytitle>pazpar2</refentrytitle>
564 <manvolnum>8</manvolnum>
568 Pazpar2 Configuration:
570 <refentrytitle>pazpar2_conf</refentrytitle>
571 <manvolnum>5</manvolnum>
577 <!-- Keep this comment at the end of the file
582 sgml-minimize-attributes:nil
583 sgml-always-quote-attributes:t
586 sgml-parent-document:nil
587 sgml-local-catalogs: nil
588 sgml-namecase-general:t