doc/pazpar2_protocol.xml

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
   2  "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
   3 [
   4      <!ENTITY % local SYSTEM "local.ent">
   5      %local;
   6      <!ENTITY % entities SYSTEM "entities.ent">
   7      %entities;
   8      <!ENTITY % common SYSTEM "common/common.ent">
   9      %common;
  10 ]>
  11 <!-- $Id: pazpar2_protocol.xml,v 1.6 2007-04-11 04:35:35 quinn Exp $ -->
  12 <refentry id="pazpar2_protocol">
  13  <refentryinfo>
  14   <productname>Pazpar2</productname>
  15   <productnumber>&version;</productnumber>
  16  </refentryinfo>
  17  <refmeta>
  18   <refentrytitle>Pazpar2 protocol</refentrytitle>
  19   <manvolnum>7</manvolnum>
  20  </refmeta>
  21
  22  <refnamediv>
  23   <refname>pazpar2_protocol</refname>
  24   <refpurpose>The webservice protocol of Pazpar2</refpurpose>
  25  </refnamediv>
  26
  27  <refsect1><title>DESCRIPTION</title>
  28   <para>
  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.
  37   </para>
  38   <para>
  39    Each command is described in sub sections to follow.
  40   </para>
  41   <refsect2 id="command-init"><title>init</title>
  42    <para>
  43     Initializes a session.
  44     Returns session ID to be used in subsequent requests.
  45    </para>
  46    <para>
  47     Example:
  48     <screen>
  49      search.pz2?command=init
  50     </screen>
  51    </para>
  52    <para>
  53     Response:
  54    </para>
  55    <screen><![CDATA[
  56     <init>
  57      <status>OK</status>
  58      <session>2044502273</session>
  59     </init>
  60 ]]></screen>
  61    <para>
  62      The
  63   </refsect2>
  64
  65   <refsect2 id="command-ping"><title>ping</title>
  66    <para>
  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
  69     activity.
  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.
  72    </para>
  73    <para>
  74     Example:
  75     <screen><![CDATA[
  76      search.pz?command=ping&session=2044502273
  77 ]]>
  78     </screen>
  79     Response:
  80    <screen><![CDATA[
  81 <ping>
  82   <status>OK</status>
  83 </ping>
  84 ]]></screen>
  85    </para>
  86   </refsect2>
  87   <refsect2 id="command-search"><title>search</title>
  88    <para>
  89     Launches a search, parameters:
  90
  91     <variablelist>
  92      <varlistentry>
  93       <term>session</term>
  94       <listitem>
  95        <para>
  96         Session ID
  97         </para>
  98       </listitem>
  99      </varlistentry>
 100      <varlistentry>
 101       <term>query</term>
 102       <listitem>
 103        <para>
 104         CCL query
 105         </para>
 106       </listitem>
 107      </varlistentry>
 108     </variablelist>
 109
 110    </para>
 111    <para>
 112     Example:
 113     <screen><![CDATA[
 114 search.pz2?session=2044502273&command=search&query=computer+science
 115 ]]>
 116      </screen>
 117     Response:
 118    <screen><![CDATA[
 119 <search>
 120   <status>OK</status>
 121 </search>
 122      ]]></screen>
 123    </para>
 124   </refsect2>
 125
 126   <refsect2 id="command-stat">
 127    <title>stat</title>
 128    <para>
 129     Provides status information about an ongoing search. Parameters:
 130
 131     <variablelist>
 132      <varlistentry>
 133       <term>session</term>
 134       <listitem>
 135        <para>
 136         Session ID
 137         </para>
 138       </listitem>
 139      </varlistentry>
 140     </variablelist>
 141
 142    </para>
 143    <para>
 144     Example:
 145    <screen><![CDATA[
 146 search.pz2?session=2044502273&command=stat
 147     ]]></screen>
 148     Output
 149     <screen><![CDATA[
 150 <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
 163 </stat>
 164      ]]></screen>
 165   </para>
 166   </refsect2>
 167
 168   <refsect2 id="command-show">
 169    <title>show</title>
 170    <para>
 171     Shows records retrieved. Parameters:
 172     <variablelist>
 173      <varlistentry>
 174       <term>session</term>
 175       <listitem>
 176        <para>
 177         Session ID
 178         </para>
 179       </listitem>
 180      </varlistentry>
 181
 182      <varlistentry>
 183       <term>start</term>
 184       <listitem>
 185        <para>First record to show - 0-indexed.</para>
 186       </listitem>
 187      </varlistentry>
 188
 189      <varlistentry>
 190       <term>num</term>
 191       <listitem>
 192        <para>
 193         Number of records to show If omitted, 20 is used.
 194        </para>
 195       </listitem>
 196      </varlistentry>
 197
 198      <varlistentry>
 199       <term>block</term>
 200       <listitem>
 201        <para>
 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.
 205        </para>
 206       </listitem>
 207      </varlistentry>
 208
 209      <varlistentry>
 210        <term>sort</term>
 211        <listitem>
 212          <para>
 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
 218            the default.
 219          </para>
 220         </listitem>
 221       </varlistentry>
 222
 223     </variablelist>
 224    </para>
 225    <para>
 226     Example:
 227     <screen><![CDATA[
 228 search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
 229 ]]></screen>
 230     Output:
 231     <screen><![CDATA[
 232 <show>
 233   <status>OK</status>
 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
 239   <hit>
 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
 243   </hit>
 244   <hit>
 245     <md-title>
 246   Computer processing of dynamic images from an Anger scintillation camera :
 247   the proceedings of a workshop /
 248     </md-title>
 249     <recid>2</recid>
 250   </hit>
 251 </show>
 252      ]]></screen>
 253    </para>
 254   </refsect2>
 255
 256   <refsect2 id="command-record">
 257    <title>record</title>
 258    <para>
 259     Retrieves a detailed record. Parameters:
 260
 261     <variablelist>
 262      <varlistentry>
 263       <term>session</term>
 264       <listitem>
 265        <para>
 266         Session ID
 267         </para>
 268       </listitem>
 269      </varlistentry>
 270
 271      <varlistentry>
 272       <term>id</term>
 273       <listitem>
 274        <para>
 275         record ID as provided by the
 276         <link linkend="command-show">show</link> command.
 277         </para>
 278       </listitem>
 279      </varlistentry>
 280     </variablelist>
 281    </para>
 282    <para>
 283     Example:
 284     <screen><![CDATA[
 285 search.pz2?session=605047297&command=record&id=3
 286 ]]></screen>
 287
 288     Example output:
 289
 290     <screen><![CDATA[
 291 <record>
 292   <md-title>
 293         The Puget Sound Region : a portfolio of thematic computer maps /
 294   </md-title>
 295   <md-date>1974</md-date>
 296   <md-author>Mairs, John W.</md-author>
 297   <md-subject>Cartography</md-subject>
 298 </record>
 299     <screen><![CDATA[
 300 ]]></screen>
 301    </para>
 302   </refsect2>
 303
 304   <refsect2 id="command-termlist">
 305    <title>termlist</title>
 306    <para>
 307     Retrieves term list(s). Parameters:
 308
 309 session
 310 name       -- comma-separated list of termlist names (default "subject")
 311
 312    </para>
 313    <para>
 314     Example:
 315     <screen><![CDATA[
 316 search.pz2?session=2044502273&command=termlist&name=author,subject
 317 ]]></screen>
 318 Output:
 319     <screen><![CDATA[
 320 <termlist>
 321   <activeclients>3</activeclients>
 322   <list name="author">
 323     <term>
 324       <name>Donald Knuth</name>
 325       <frequency>10</frequency>
 326     </term>
 327       <term>
 328       <name>Robert Pirsig</name>
 329       <frequency>2</frequency>
 330     </term>
 331   </list>
 332   <list name="subject">
 333     <term>
 334       <name>Computer programming</name>
 335       <frequency>10</frequency>
 336     </term>
 337   </list>
 338 </termlist>
 339 ]]></screen>
 340     </para>
 341
 342    <para>
 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.
 349    </para>
 350    <para>
 351     Example
 352     <screen><![CDATA[
 353 <term>
 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
 358 </term>
 359 ]]></screen>
 360     </para>
 361   </refsect2>
 362
 363
 364   <refsect2 id="command-bytarget">
 365    <title>bytarget</title>
 366    <para>
 367     Returns information about the status of each active client. Parameters:
 368
 369     <variablelist>
 370      <varlistentry>
 371       <term>session</term>
 372       <listitem>
 373        <para>
 374           Session Id.
 375         </para>
 376       </listitem>
 377      </varlistentry>
 378     </variablelist>
 379    </para>
 380    <para>
 381     Example:
 382     <screen><![CDATA[
 383 search.pz2?session=605047297&command=record&id=3
 384 ]]></screen>
 385
 386     Example output:
 387
 388     <screen><![CDATA[
 389 <bytarget>
 390   <status>OK</status>
 391   <target>
 392     <id>z3950.loc.gov/voyager/</id>
 393     <hits>10000</hits>
 394     <diagnostic>0</diagnostic>
 395     <records>65</records>
 396     <state>Client_Presenting</state>
 397   </target>
 398   <!-- ... more target nodes below as necessary -->
 399 </bytarget>
 400 ]]></screen>
 401
 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.
 406    </para>
 407   </refsect2>
 408
 409  </refsect1>
 410 </refentry>
 411
 412 <!-- Keep this comment at the end of the file
 413 Local variables:
 414 mode: sgml
 415 sgml-omittag:t
 416 sgml-shorttag:t
 417 sgml-minimize-attributes:nil
 418 sgml-always-quote-attributes:t
 419 sgml-indent-step:1
 420 sgml-indent-data:t
 421 sgml-parent-document:nil
 422 sgml-local-catalogs: nil
 423 sgml-namecase-general:t
 424 End:
 425 -->