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.2 2007-01-12 15:21:04 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 configuration.
33 This way, the webserver can host the user interface (itself dynamic
34 or static HTML), and AJAX-style calls can be used from JS to interact
35 with the search logic.
38 Each command is described in sub sections to follow.
40 <refsect2 id="command-init"><title>init</title>
42 Initializes a session.
43 Returns session ID to be used in subsequent requests.
48 search.pz2?command=init
57 <session>2044502273</session>
62 <refsect2 id="command-ping"><title>ping</title>
64 Keeps a session alive. An idle session will time out after one minute.
65 The ping command can be used to keep the session alive absent other
67 It is suggested that any browser client have a simple alarm handler which
68 sends a ping every 50 seconds or so once a session has been initialized.
73 search.pz?command=ping&session=2044502273
84 <refsect2 id="command-search"><title>search</title>
86 Launches a search, parameters:
111 search.pz2?session=2044502273&command=search&query=computer
123 <refsect2 id="command-stat">
126 Provides status of ongoing search. Parameters:
143 search.pz2?session=2044502273&command=stat
148 <activeclients>3</activeclients>
149 <hits>7</hits> -- Total hitcount
150 <records>7</records> -- Total number of records fetched
151 <clients>1</clients> -- Total number of associated clients
152 <unconnected>0</unconnected> -- Number of disconnected clients
153 <connecting>0</connecting> -- Number of clients in connecting state
154 <initializing>0</initializing> -- Number of clients initializing
155 <searching>0</searching> -- ... searching
156 <presenting>0</presenting> -- ... presenting
157 <idle>1</idle> -- ... idle (not doing anything)
158 <failed>0</failed> -- ... Connection failed
159 <error>0</error> -- ... Error was produced somewhere
165 <refsect2 id="command-show">
168 Shows records retrieved. Parameters:
182 <para>First record to show - 0-indexed.</para>
190 Number of records to show If omitted, 20 is used.
199 If block is set, the command will hang until there are records ready
200 to display. Use this to show first records rapidly without
201 requiring rapid polling.
211 search.pz2?session=2044502273&command=show&start=0&num=2
217 <activeclients>3</activeclients>
223 <md-title>How to program a computer, by Jack Collins</md-title>
224 <count>2</count> <!-- Number of merged records -->
229 Computer processing of dynamic images from an Anger scintillation camera :
230 the proceedings of a workshop /
239 <refsect2 id="command-record">
240 <title>record</title>
242 Retrieves a detailed record. Parameters:
249 record ID as provided by the
250 <link linkend="command-show">show</link> command.
259 search.pz2?session=605047297&command=record&id=3
267 The Puget Sound Region : a portfolio of thematic computer maps /
269 <md-date>1974</md-date>
270 <md-author>Mairs, John W.</md-author>
271 <md-subject>Cartography</md-subject>
278 <refsect2 id="command-termlist">
279 <title>termlist</title>
281 Retrieves term list(s). Parameters:
284 name -- comma-separated list of termlist names (default "subject")
290 search.pz2?session=2044502273&command=termlist&name=author,subject
295 <activeclients>3</activeclients>
298 <name>Donald Knuth</name>
299 <frequency>10</frequency>
302 <name>Robert Pirsig</name>
303 <frequency>2</frequency>
306 <list name="subject">
308 <name>Computer programming</name>
309 <frequency>10</frequency>
317 For the special termlist name "xtargets", results
318 are returned about the targets which have returned the most hits.
319 The 'term' subtree has additional elements,
320 specifically a state and diagnostic field (in the example below, a
321 target ID is returned in place of 'name'.
322 This may or may not change later.
328 <name>library2.mcmaster.ca</name>
329 <frequency>11734</frequency>
330 <state>Client_Idle</state>
331 <diagnostic>0</diagnostic>
340 <!-- Keep this comment at the end of the file
345 sgml-minimize-attributes:nil
346 sgml-always-quote-attributes:t
349 sgml-parent-document:nil
350 sgml-local-catalogs: nil
351 sgml-namecase-general:t