1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
2 "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
4 <!ENTITY % local SYSTEM "local.ent">
6 <!ENTITY % entities SYSTEM "entities.ent">
8 <!ENTITY % common SYSTEM "common/common.ent">
11 <!-- $Id: pazpar2_protocol.xml,v 1.6 2007-04-11 04:35:35 quinn Exp $ -->
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>
65 <refsect2 id="command-ping"><title>ping</title>
67 Keeps a session alive. An idle session will time out after one minute.
68 The ping command can be used to keep the session alive absent other
70 It is suggested that any browser client have a simple alarm handler which
71 sends a ping every 50 seconds or so once a session has been initialized.
76 search.pz?command=ping&session=2044502273
87 <refsect2 id="command-search"><title>search</title>
89 Launches a search, parameters:
114 search.pz2?session=2044502273&command=search&query=computer+science
126 <refsect2 id="command-stat">
129 Provides status information about an ongoing search. Parameters:
146 search.pz2?session=2044502273&command=stat
151 <activeclients>3</activeclients>
152 <hits>7</hits> -- Total hitcount
153 <records>7</records> -- Total number of records fetched in last query
154 <clients>1</clients> -- Total number of associated clients
155 <unconnected>0</unconnected> -- Number of disconnected clients
156 <connecting>0</connecting> -- Number of clients in connecting state
157 <initializing>0</initializing> -- Number of clients initializing
158 <searching>0</searching> -- ... searching
159 <presenting>0</presenting> -- ... presenting
160 <idle>1</idle> -- ... idle (not doing anything)
161 <failed>0</failed> -- ... Connection failed
162 <error>0</error> -- ... Error was produced somewhere
168 <refsect2 id="command-show">
171 Shows records retrieved. Parameters:
185 <para>First record to show - 0-indexed.</para>
193 Number of records to show If omitted, 20 is used.
202 If block is set to 1, the command will hang until there are records ready
203 to display. Use this to show first records rapidly without
204 requiring rapid polling.
213 Specifies sort criteria. The argument is a comma-separated list
214 (no whitespace allowed) of sort fields, with the highest-priority
215 field first. A sort field may be followed by a colon followed by
216 the number '0' or '1', indicating whether results should be sorted in
217 increasing or decreasing order according to that field. 0==Decreasing is
228 search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
234 <activeclients>3</activeclients> -- How many clients are still working
235 <merged>6</merged> -- Number of merged records
236 <total>7</total> -- Total of all hitcounts
237 <start>0</start> -- The start number you requested
238 <num>2</num> -- Number of records retrieved
240 <md-title>How to program a computer, by Jack Collins</md-title>
241 <count>2</count> -- Number of merged records
242 <recid>6</recid> -- Record ID for this record
246 Computer processing of dynamic images from an Anger scintillation camera :
247 the proceedings of a workshop /
256 <refsect2 id="command-record">
257 <title>record</title>
259 Retrieves a detailed record. Parameters:
275 record ID as provided by the
276 <link linkend="command-show">show</link> command.
285 search.pz2?session=605047297&command=record&id=3
293 The Puget Sound Region : a portfolio of thematic computer maps /
295 <md-date>1974</md-date>
296 <md-author>Mairs, John W.</md-author>
297 <md-subject>Cartography</md-subject>
304 <refsect2 id="command-termlist">
305 <title>termlist</title>
307 Retrieves term list(s). Parameters:
310 name -- comma-separated list of termlist names (default "subject")
316 search.pz2?session=2044502273&command=termlist&name=author,subject
321 <activeclients>3</activeclients>
324 <name>Donald Knuth</name>
325 <frequency>10</frequency>
328 <name>Robert Pirsig</name>
329 <frequency>2</frequency>
332 <list name="subject">
334 <name>Computer programming</name>
335 <frequency>10</frequency>
343 For the special termlist name "xtargets", results
344 are returned about the targets which have returned the most hits.
345 The 'term' subtree has additional elements,
346 specifically a state and diagnostic field (in the example below, a
347 target ID is returned in place of 'name'.
348 This may or may not change later.
354 <name>library2.mcmaster.ca</name>
355 <frequency>11734</frequency> -- Number of hits
356 <state>Client_Idle</state> -- See the description of 'bytarget' below
357 <diagnostic>0</diagnostic> -- Z39.50 diagnostic codes
364 <refsect2 id="command-bytarget">
365 <title>bytarget</title>
367 Returns information about the status of each active client. Parameters:
383 search.pz2?session=605047297&command=record&id=3
392 <id>z3950.loc.gov/voyager/</id>
394 <diagnostic>0</diagnostic>
395 <records>65</records>
396 <state>Client_Presenting</state>
398 <!-- ... more target nodes below as necessary -->
402 The following client states are defined: Client_Connecting,
403 Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
404 Client_Searching, Client_Presenting, Client_Error, Client_Failed,
405 Client_Disconnected, Client_Stopped.
412 <!-- Keep this comment at the end of the file
417 sgml-minimize-attributes:nil
418 sgml-always-quote-attributes:t
421 sgml-parent-document:nil
422 sgml-local-catalogs: nil
423 sgml-namecase-general:t