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