doc/pazpar2_protocol.xml

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