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