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 <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      <varlistentry>
 166       <term>filter</term>
 167       <listitem>
 168        <para>
 169         Filtering.
 170         </para>
 171       </listitem>
 172      </varlistentry>
 173     </variablelist>
 174
 175    </para>
 176    <para>
 177     Example:
 178     <screen><![CDATA[
 179 search.pz2?session=2044502273&command=search&query=computer+science
 180 ]]>
 181      </screen>
 182     Response:
 183    <screen><![CDATA[
 184 <search>
 185   <status>OK</status>
 186 </search>
 187      ]]></screen>
 188    </para>
 189   </refsect2>
 190
 191   <refsect2 id="command-stat">
 192    <title>stat</title>
 193    <para>
 194     Provides status information about an ongoing search. Parameters:
 195
 196     <variablelist>
 197      <varlistentry>
 198       <term>session</term>
 199       <listitem>
 200        <para>
 201         Session ID
 202         </para>
 203       </listitem>
 204      </varlistentry>
 205     </variablelist>
 206
 207    </para>
 208    <para>
 209     Example:
 210    <screen><![CDATA[
 211 search.pz2?session=2044502273&command=stat
 212     ]]></screen>
 213     Output
 214     <screen><![CDATA[
 215 <stat>
 216   <activeclients>3</activeclients>
 217   <hits>7</hits>                   -- Total hitcount
 218   <records>7</records>             -- Total number of records fetched in last query
 219   <clients>1</clients>             -- Total number of associated clients
 220   <unconnected>0</unconnected>     -- Number of disconnected clients
 221   <connecting>0</connecting>       -- Number of clients in connecting state
 222   <initializing>0</initializing>   -- Number of clients initializing
 223   <searching>0</searching>         -- ... searching
 224   <presenting>0</presenting>       -- ... presenting
 225   <idle>1</idle>                   -- ... idle (not doing anything)
 226   <failed>0</failed>               -- ... Connection failed
 227   <error>0</error>                 -- ... Error was produced somewhere
 228 </stat>
 229      ]]></screen>
 230   </para>
 231   </refsect2>
 232
 233   <refsect2 id="command-show">
 234    <title>show</title>
 235    <para>
 236     Shows records retrieved. Parameters:
 237     <variablelist>
 238      <varlistentry>
 239       <term>session</term>
 240       <listitem>
 241        <para>
 242         Session ID
 243         </para>
 244       </listitem>
 245      </varlistentry>
 246
 247      <varlistentry>
 248       <term>start</term>
 249       <listitem>
 250        <para>First record to show - 0-indexed.</para>
 251       </listitem>
 252      </varlistentry>
 253
 254      <varlistentry>
 255       <term>num</term>
 256       <listitem>
 257        <para>
 258         Number of records to show If omitted, 20 is used.
 259        </para>
 260       </listitem>
 261      </varlistentry>
 262
 263      <varlistentry>
 264       <term>block</term>
 265       <listitem>
 266        <para>
 267         If block is set to 1, the command will hang until there are records ready
 268         to display. Use this to show first records rapidly without
 269         requiring rapid polling.
 270        </para>
 271       </listitem>
 272      </varlistentry>
 273
 274      <varlistentry>
 275       <term>sort</term>
 276       <listitem>
 277        <para>
 278         Specifies sort criteria. The argument is a comma-separated list
 279         (no whitespace allowed) of sort fields, with the highest-priority
 280         field first. A sort field may be followed by a colon followed by
 281         the number '0' or '1', indicating whether results should be sorted in
 282         increasing or decreasing order according to that field. 0==Decreasing is
 283         the default.
 284        </para>
 285       </listitem>
 286      </varlistentry>
 287
 288     </variablelist>
 289    </para>
 290    <para>
 291     Example:
 292     <screen><![CDATA[
 293 search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
 294 ]]></screen>
 295     Output:
 296     <screen><![CDATA[
 297 <show>
 298   <status>OK</status>
 299   <activeclients>3</activeclients>     -- How many clients are still working
 300   <merged>6</merged>                   -- Number of merged records
 301   <total>7</total>                     -- Total of all hitcounts
 302   <start>0</start>                     -- The start number you requested
 303   <num>2</num>                         -- Number of records retrieved
 304   <hit>
 305     <md-title>How to program a computer, by Jack Collins</md-title>
 306     <count>2</count>                   -- Number of merged records
 307     <recid>6</recid>                   -- Record ID for this record
 308   </hit>
 309   <hit>
 310     <md-title>
 311   Computer processing of dynamic images from an Anger scintillation camera :
 312   the proceedings of a workshop /
 313     </md-title>
 314     <recid>2</recid>
 315   </hit>
 316 </show>
 317      ]]></screen>
 318    </para>
 319   </refsect2>
 320
 321   <refsect2 id="command-record">
 322    <title>record</title>
 323    <para>
 324     Retrieves a detailed record. Unlike the
 325     <link linkend="command-show">show</link> command, this command
 326     returns metadata records before merging takes place. Parameters:
 327
 328     <variablelist>
 329      <varlistentry>
 330       <term>session</term>
 331       <listitem>
 332        <para>
 333         Session ID
 334        </para>
 335       </listitem>
 336      </varlistentry>
 337
 338      <varlistentry>
 339       <term>id</term>
 340       <listitem>
 341        <para>
 342         record ID as provided by the
 343         <link linkend="command-show">show</link> command.
 344         </para>
 345       </listitem>
 346      </varlistentry>
 347
 348      <varlistentry>
 349       <term>offset</term>
 350       <listitem>
 351        <para>
 352         This optional parameter is an integer which, when given, makes
 353         Pazpar2 return the raw record for a target. The raw record
 354         from first target is numbered 0, second numbered 1, etc.
 355         When a raw record is returned Pazpar2 will XSLT transform the
 356         record but an XML version is returned. All ISO2709 records are
 357         returned as MARCXML. OPAC records are returned as YAZ'
 358         OPAC with an MARCXML sibling.
 359        </para>
 360        <para>
 361         When offset is not given the Pazpar2 metadata for the record
 362         is returned and with metadata for each targets' data specified
 363         in a 'location' list.
 364        </para>
 365       </listitem>
 366      </varlistentry>
 367
 368      <varlistentry>
 369       <term>syntax</term>
 370       <listitem>
 371        <para>
 372         This optional parameter is the record syntax used for raw
 373         transfer (i.e. when offset is specified). If syntax is not given,
 374         but offset is used, the value of pz:requestsyntax is used.
 375        </para>
 376       </listitem>
 377      </varlistentry>
 378
 379      <varlistentry>
 380       <term>esn</term>
 381       <listitem>
 382        <para>
 383         This optional parameter is the element set name used to retrieval
 384         of a raw record (i.e. when offset is specified).
 385         If esn is not given, but offset is used, the value of pz:elements
 386         is used.
 387        </para>
 388       </listitem>
 389      </varlistentry>
 390
 391      <varlistentry>
 392       <term>binary</term>
 393       <listitem>
 394        <para>
 395         This optional parameter enables "binary" response for retrieval
 396         of a raw record (i.e. when offset is specified). For binary
 397         responses the record is <emphasis>not</emphasis> converted to
 398         XML and the HTTP content type is application/octet-stream.
 399        </para>
 400       </listitem>
 401      </varlistentry>
 402
 403     </variablelist>
 404    </para>
 405    <para>
 406     Example:
 407     <screen><![CDATA[
 408 search.pz2?session=605047297&command=record&id=3
 409 ]]></screen>
 410
 411     Example output:
 412
 413     <screen><![CDATA[
 414 <record>
 415   <md-title>
 416         The Puget Sound Region : a portfolio of thematic computer maps /
 417   </md-title>
 418   <md-date>1974</md-date>
 419   <md-author>Mairs, John W.</md-author>
 420   <md-subject>Cartography</md-subject>
 421 </record>
 422 ]]></screen>
 423    </para>
 424   </refsect2>
 425
 426   <refsect2 id="command-termlist">
 427    <title>termlist</title>
 428    <para>
 429     Retrieves term list(s). Parameters:
 430
 431     <variablelist>
 432      <varlistentry>
 433       <term>session</term>
 434       <listitem>
 435        <para>
 436         Session Id.
 437        </para>
 438       </listitem>
 439      </varlistentry>
 440      <varlistentry>
 441       <term>name</term>
 442       <listitem>
 443        <para>
 444         comma-separated list of termlist names (default "subject")
 445        </para>
 446       </listitem>
 447      </varlistentry>
 448     </variablelist>
 449    </para>
 450    <para>
 451     Example:
 452     <screen><![CDATA[
 453 search.pz2?session=2044502273&command=termlist&name=author,subject
 454 ]]></screen>
 455 Output:
 456     <screen><![CDATA[
 457 <termlist>
 458   <activeclients>3</activeclients>
 459   <list name="author">
 460     <term>
 461       <name>Donald Knuth</name>
 462       <frequency>10</frequency>
 463     </term>
 464       <term>
 465       <name>Robert Pirsig</name>
 466       <frequency>2</frequency>
 467     </term>
 468   </list>
 469   <list name="subject">
 470     <term>
 471       <name>Computer programming</name>
 472       <frequency>10</frequency>
 473     </term>
 474   </list>
 475 </termlist>
 476 ]]></screen>
 477     </para>
 478
 479    <para>
 480     For the special termlist name "xtargets", results
 481     are returned about the targets which have returned the most hits.
 482     The 'term' subtree has additional elements,
 483     specifically a state and diagnostic field (in the example below, a
 484     target ID is returned in place of 'name'.
 485     This may or may not change later.
 486    </para>
 487    <para>
 488     Example
 489     <screen><![CDATA[
 490 <term>
 491   <name>library2.mcmaster.ca</name>
 492   <frequency>11734</frequency>         -- Number of hits
 493   <state>Client_Idle</state>           -- See the description of 'bytarget' below
 494   <diagnostic>0</diagnostic>           -- Z39.50 diagnostic codes
 495 </term>
 496 ]]></screen>
 497     </para>
 498   </refsect2>
 499
 500
 501   <refsect2 id="command-bytarget">
 502    <title>bytarget</title>
 503    <para>
 504     Returns information about the status of each active client. Parameters:
 505
 506     <variablelist>
 507      <varlistentry>
 508       <term>session</term>
 509       <listitem>
 510        <para>
 511         Session Id.
 512         </para>
 513       </listitem>
 514      </varlistentry>
 515     </variablelist>
 516    </para>
 517    <para>
 518     Example:
 519     <screen><![CDATA[
 520 search.pz2?session=605047297&command=bytarget&id=3
 521 ]]></screen>
 522
 523     Example output:
 524
 525     <screen><![CDATA[
 526 <bytarget>
 527   <status>OK</status>
 528   <target>
 529     <id>z3950.loc.gov/voyager/</id>
 530     <hits>10000</hits>
 531     <diagnostic>0</diagnostic>
 532     <records>65</records>
 533     <state>Client_Presenting</state>
 534   </target>
 535   <!-- ... more target nodes below as necessary -->
 536 </bytarget>
 537 ]]></screen>
 538
 539     The following client states are defined: Client_Connecting,
 540     Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
 541     Client_Searching, Client_Presenting, Client_Error, Client_Failed,
 542     Client_Disconnected, Client_Stopped, Client_Continue.
 543    </para>
 544   </refsect2>
 545
 546  </refsect1>
 547  <refsect1><title>SEE ALSO</title>
 548   <para>
 549    Pazpar2:
 550    <citerefentry>
 551     <refentrytitle>pazpar2</refentrytitle>
 552     <manvolnum>8</manvolnum>
 553    </citerefentry>
 554   </para>
 555   <para>
 556    Pazpar2 Configuration:
 557    <citerefentry>
 558     <refentrytitle>pazpar2_conf</refentrytitle>
 559     <manvolnum>5</manvolnum>
 560    </citerefentry>
 561   </para>
 562  </refsect1>
 563 </refentry>
 564
 565 <!-- Keep this comment at the end of the file
 566 Local variables:
 567 mode: sgml
 568 sgml-omittag:t
 569 sgml-shorttag:t
 570 sgml-minimize-attributes:nil
 571 sgml-always-quote-attributes:t
 572 sgml-indent-step:1
 573 sgml-indent-data:t
 574 sgml-parent-document:nil
 575 sgml-local-catalogs: nil
 576 sgml-namecase-general:t
 577 End:
 578 -->