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