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.1 2007-01-12 14:54:58 adam 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 required and specifies
31 command. Any request not recognized as a webservice request as described,
32 are forwarded to the HTTP server specified in option -p.
35 Each command is described in sub sections to follow.
37 <refsect2 id="command-init"><title>init</title>
39 Initializes a session.
40 Returns session ID to be used in subsequent requests.
45 search.pz2?command=init
54 <session>2044502273</session>
59 <refsect2 id="command-ping"><title>ping</title>
61 Keeps a session alive. An idle session will time out after one minute.
62 The ping command can be used to keep the session alive absent other
64 It is suggested that any browser client have a simple alarm handler which
65 sends a ping every 50 seconds or so once a session has been initialized.
70 search.pz?command=ping&session=2044502273
81 <refsect2 id="command-search"><title>search</title>
83 Launches a search, parameters:
108 search.pz2?session=2044502273&command=search&query=computer
120 <refsect2 id="command-stat">
123 Provides status of ongoing search. Parameters:
140 search.pz2?session=2044502273&command=stat
145 <activeclients>3</activeclients>
146 <hits>7</hits> -- Total hitcount
147 <records>7</records> -- Total number of records fetched
148 <clients>1</clients> -- Total number of associated clients
149 <unconnected>0</unconnected> -- Number of disconnected clients
150 <connecting>0</connecting> -- Number of clients in connecting state
151 <initializing>0</initializing> -- Number of clients initializing
152 <searching>0</searching> -- ... searching
153 <presenting>0</presenting> -- ... presenting
154 <idle>1</idle> -- ... idle (not doing anything)
155 <failed>0</failed> -- ... Connection failed
156 <error>0</error> -- ... Error was produced somewhere
162 <refsect2 id="command-show">
165 Shows records retrieved. Parameters:
179 <para>First record to show - 0-indexed.</para>
187 Number of records to show If omitted, 20 is used.
196 If block is set, the command will hang until there are records ready
197 to display. Use this to show first records rapidly without
198 requiring rapid polling.
208 search.pz2?session=2044502273&command=show&start=0&num=2
214 <activeclients>3</activeclients>
220 <md-title>How to program a computer, by Jack Collins</md-title>
221 <count>2</count> <!-- Number of merged records -->
226 Computer processing of dynamic images from an Anger scintillation camera :
227 the proceedings of a workshop /
236 <refsect2 id="command-record">
237 <title>record</title>
239 Retrieves a detailed record. Parameters:
246 record ID as provided by the
247 <link linkend="command-show">show</link> command.
256 search.pz2?session=605047297&command=record&id=3
264 The Puget Sound Region : a portfolio of thematic computer maps /
266 <md-date>1974</md-date>
267 <md-author>Mairs, John W.</md-author>
268 <md-subject>Cartography</md-subject>
275 <refsect2 id="command-termlist">
276 <title>termlist</title>
278 Retrieves term list(s). Parameters:
281 name -- comma-separated list of termlist names (default "subject")
287 search.pz2?session=2044502273&command=termlist&name=author,subject
292 <activeclients>3</activeclients>
295 <name>Donald Knuth</name>
296 <frequency>10</frequency>
299 <name>Robert Pirsig</name>
300 <frequency>2</frequency>
303 <list name="subject">
305 <name>Computer programming</name>
306 <frequency>10</frequency>
314 For the special termlist name "xtargets", results
315 are returned about the targets which have returned the most hits.
316 The 'term' subtree has additional elements,
317 specifically a state and diagnostic field (in the example below, a
318 target ID is returned in place of 'name'.
319 This may or may not change later.
325 <name>library2.mcmaster.ca</name>
326 <frequency>11734</frequency>
327 <state>Client_Idle</state>
328 <diagnostic>0</diagnostic>
337 <!-- Keep this comment at the end of the file
342 sgml-minimize-attributes:nil
343 sgml-always-quote-attributes:t
346 sgml-parent-document:nil
347 sgml-local-catalogs: nil
348 sgml-namecase-general:t