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.4 2007-01-19 19:08:00 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   </refsect2>
  62
  63   <refsect2 id="command-ping"><title>ping</title>
  64    <para>
  65     Keeps a session alive. An idle session will time out after one minute.
  66     The ping command can be used to keep the session alive absent other
  67     activity.
  68     It is suggested that any browser client have a simple alarm handler which
  69     sends a ping every 50 seconds or so once a session has been initialized.
  70    </para>
  71    <para>
  72     Example:
  73     <screen><![CDATA[
  74      search.pz?command=ping&session=2044502273
  75 ]]>
  76     </screen>
  77     Response:
  78    <screen><![CDATA[
  79 <ping>
  80   <status>OK</status>
  81 </ping>
  82 ]]></screen>
  83    </para>
  84   </refsect2>
  85   <refsect2 id="command-search"><title>search</title>
  86    <para>
  87     Launches a search, parameters:
  88
  89     <variablelist>
  90      <varlistentry>
  91       <term>session</term>
  92       <listitem>
  93        <para>
  94         Session ID
  95         </para>
  96       </listitem>
  97      </varlistentry>
  98      <varlistentry>
  99       <term>query</term>
 100       <listitem>
 101        <para>
 102         CCL query
 103         </para>
 104       </listitem>
 105      </varlistentry>
 106     </variablelist>
 107
 108    </para>
 109    <para>
 110     Example:
 111     <screen><![CDATA[
 112 search.pz2?session=2044502273&command=search&query=computer+science
 113 ]]>
 114      </screen>
 115     Response:
 116    <screen><![CDATA[
 117 <search>
 118   <status>OK</status>
 119 </search>
 120      ]]></screen>
 121    </para>
 122   </refsect2>
 123
 124   <refsect2 id="command-stat">
 125    <title>stat</title>
 126    <para>
 127     Provides status information about an ongoing search. Parameters:
 128
 129     <variablelist>
 130      <varlistentry>
 131       <term>session</term>
 132       <listitem>
 133        <para>
 134         Session ID
 135         </para>
 136       </listitem>
 137      </varlistentry>
 138     </variablelist>
 139
 140    </para>
 141    <para>
 142     Example:
 143    <screen><![CDATA[
 144 search.pz2?session=2044502273&command=stat
 145     ]]></screen>
 146     Output
 147     <screen><![CDATA[
 148 <stat>
 149   <activeclients>3</activeclients>
 150   <hits>7</hits>                   -- Total hitcount
 151   <records>7</records>             -- Total number of records fetched in last query
 152   <clients>1</clients>             -- Total number of associated clients
 153   <unconnected>0</unconnected>     -- Number of disconnected clients
 154   <connecting>0</connecting>       -- Number of clients in connecting state
 155   <initializing>0</initializing>   -- Number of clients initializing
 156   <searching>0</searching>         -- ... searching
 157   <presenting>0</presenting>       -- ... presenting
 158   <idle>1</idle>                   -- ... idle (not doing anything)
 159   <failed>0</failed>               -- ... Connection failed
 160   <error>0</error>                 -- ... Error was produced somewhere
 161 </stat>
 162      ]]></screen>
 163   </para>
 164   </refsect2>
 165
 166   <refsect2 id="command-show">
 167    <title>show</title>
 168    <para>
 169     Shows records retrieved. Parameters:
 170     <variablelist>
 171      <varlistentry>
 172       <term>session</term>
 173       <listitem>
 174        <para>
 175         Session ID
 176         </para>
 177       </listitem>
 178      </varlistentry>
 179
 180      <varlistentry>
 181       <term>start</term>
 182       <listitem>
 183        <para>First record to show - 0-indexed.</para>
 184       </listitem>
 185      </varlistentry>
 186
 187      <varlistentry>
 188       <term>num</term>
 189       <listitem>
 190        <para>
 191         Number of records to show If omitted, 20 is used.
 192        </para>
 193       </listitem>
 194      </varlistentry>
 195
 196      <varlistentry>
 197       <term>block</term>
 198       <listitem>
 199        <para>
 200         If block is set to 1, the command will hang until there are records ready
 201         to display. Use this to show first records rapidly without
 202         requiring rapid polling.
 203        </para>
 204       </listitem>
 205      </varlistentry>
 206
 207      <varlistentry>
 208        <term>sort</term>
 209        <listitem>
 210          <para>
 211            Specifies sort criteria. The argument is a comma-separated list
 212            (no whitespace allowed) of sort fields, with the highest-priority
 213            field first. A sort field may be followed by a colon followed by
 214            the number '0' or '1', indicating whether results should be sorted in
 215            increasing or decreasing order according to that field. 0==Decreasing is
 216            the default.
 217          </para>
 218         </listitem>
 219       </varlistentry>
 220
 221     </variablelist>
 222    </para>
 223    <para>
 224     Example:
 225     <screen><![CDATA[
 226 search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
 227 ]]></screen>
 228     Output:
 229     <screen><![CDATA[
 230 <show>
 231   <status>OK</status>
 232   <activeclients>3</activeclients>     -- How many clients are still working
 233   <merged>6</merged>                   -- Number of merged records
 234   <total>7</total>                     -- Total of all hitcounts
 235   <start>0</start>                     -- The start number you requested
 236   <num>2</num>                         -- Number of records retrieved
 237   <hit>
 238     <md-title>How to program a computer, by Jack Collins</md-title>
 239     <count>2</count>                   -- Number of merged records
 240     <recid>6</recid>                   -- Record ID for this record
 241   </hit>
 242   <hit>
 243     <md-title>
 244   Computer processing of dynamic images from an Anger scintillation camera :
 245   the proceedings of a workshop /
 246     </md-title>
 247     <recid>2</recid>
 248   </hit>
 249 </show>
 250      ]]></screen>
 251    </para>
 252   </refsect2>
 253
 254   <refsect2 id="command-record">
 255    <title>record</title>
 256    <para>
 257     Retrieves a detailed record. Parameters:
 258
 259     <variablelist>
 260      <varlistentry>
 261       <term>session</term>
 262       <listitem>
 263        <para>
 264         Session ID
 265         </para>
 266       </listitem>
 267      </varlistentry>
 268
 269      <varlistentry>
 270       <term>id</term>
 271       <listitem>
 272        <para>
 273         record ID as provided by the
 274         <link linkend="command-show">show</link> command.
 275         </para>
 276       </listitem>
 277      </varlistentry>
 278     </variablelist>
 279    </para>
 280    <para>
 281     Example:
 282     <screen><![CDATA[
 283 search.pz2?session=605047297&command=record&id=3
 284 ]]></screen>
 285
 286     Example output:
 287
 288     <screen><![CDATA[
 289 <record>
 290   <md-title>
 291         The Puget Sound Region : a portfolio of thematic computer maps /
 292   </md-title>
 293   <md-date>1974</md-date>
 294   <md-author>Mairs, John W.</md-author>
 295   <md-subject>Cartography</md-subject>
 296 </record>
 297     <screen><![CDATA[
 298 ]]></screen>
 299    </para>
 300   </refsect2>
 301
 302   <refsect2 id="command-termlist">
 303    <title>termlist</title>
 304    <para>
 305     Retrieves term list(s). Parameters:
 306
 307 session
 308 name       -- comma-separated list of termlist names (default "subject")
 309
 310    </para>
 311    <para>
 312     Example:
 313     <screen><![CDATA[
 314 search.pz2?session=2044502273&command=termlist&name=author,subject
 315 ]]></screen>
 316 Output:
 317     <screen><![CDATA[
 318 <termlist>
 319   <activeclients>3</activeclients>
 320   <list name="author">
 321     <term>
 322       <name>Donald Knuth</name>
 323       <frequency>10</frequency>
 324     </term>
 325       <term>
 326       <name>Robert Pirsig</name>
 327       <frequency>2</frequency>
 328     </term>
 329   </list>
 330   <list name="subject">
 331     <term>
 332       <name>Computer programming</name>
 333       <frequency>10</frequency>
 334     </term>
 335   </list>
 336 </termlist>
 337 ]]></screen>
 338     </para>
 339
 340    <para>
 341     For the special termlist name "xtargets", results
 342     are returned about the targets which have returned the most hits.
 343     The 'term' subtree has additional elements,
 344     specifically a state and diagnostic field (in the example below, a
 345     target ID is returned in place of 'name'.
 346     This may or may not change later.
 347    </para>
 348    <para>
 349     Example
 350     <screen><![CDATA[
 351 <term>
 352   <name>library2.mcmaster.ca</name>
 353   <frequency>11734</frequency>         -- Number of hits
 354   <state>Client_Idle</state>           -- See the description of 'bytarget' below
 355   <diagnostic>0</diagnostic>           -- Z39.50 diagnostic codes
 356 </term>
 357 ]]></screen>
 358     </para>
 359   </refsect2>
 360
 361
 362   <refsect2 id="command-bytarget">
 363    <title>bytarget</title>
 364    <para>
 365     Returns information about the status of each active client. Parameters:
 366
 367     <variablelist>
 368      <varlistentry>
 369       <term>session</term>
 370       <listitem>
 371        <para>
 372           Session Id.
 373         </para>
 374       </listitem>
 375      </varlistentry>
 376     </variablelist>
 377    </para>
 378    <para>
 379     Example:
 380     <screen><![CDATA[
 381 search.pz2?session=605047297&command=record&id=3
 382 ]]></screen>
 383
 384     Example output:
 385
 386     <screen><![CDATA[
 387 <bytarget>
 388   <status>OK</status>
 389   <target>
 390     <id>z3950.loc.gov/voyager/</id>
 391     <hits>10000</hits>
 392     <diagnostic>0</diagnostic>
 393     <records>65</records>
 394     <state>Client_Presenting</state>
 395   </target>
 396   <!-- ... more target nodes below as necessary -->
 397 </bytarget>
 398     <screen><![CDATA[
 399 ]]></screen>
 400
 401    The following client states are defined: Client_Connecting,
 402    Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
 403    Client_Searching, Client_Presenting, Client_Error, Client_Failed,
 404    Client_Disconnected, Client_Stopped.
 405    </para>
 406   </refsect2>
 407
 408  </refsect1>
 409 </refentry>
 410
 411 <!-- Keep this comment at the end of the file
 412 Local variables:
 413 mode: sgml
 414 sgml-omittag:t
 415 sgml-shorttag:t
 416 sgml-minimize-attributes:nil
 417 sgml-always-quote-attributes:t
 418 sgml-indent-step:1
 419 sgml-indent-data:t
 420 sgml-parent-document:nil
 421 sgml-local-catalogs: nil
 422 sgml-namecase-general:t
 423 End:
 424 -->