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