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
  77      <varlistentry>
  78       <term>service</term>
  79       <listitem>
  80        <para>
  81         If this is defined it specifies a service ID. Makes the session use
  82         the service with this ID. If this is setting is omitted, the
  83         session will use the unnamed service in the Pazpar2 configuration.
  84         </para>
  85       </listitem>
  86      </varlistentry>
  87     </variablelist>
  88    </para>
  89   </refsect2>
  90
  91   <refsect2 id="command-ping"><title>ping</title>
  92    <para>
  93     Keeps a session alive. An idle session will time out after one minute.
  94     The ping command can be used to keep the session alive absent other
  95     activity.
  96     It is suggested that any browser client have a simple alarm handler which
  97     sends a ping every 50 seconds or so once a session has been initialized.
  98    </para>
  99    <para>
 100     Example:
 101     <screen><![CDATA[
 102      search.pz?command=ping&session=2044502273
 103 ]]>
 104     </screen>
 105     Response:
 106    <screen><![CDATA[
 107 <ping>
 108   <status>OK</status>
 109 </ping>
 110 ]]></screen>
 111    </para>
 112   </refsect2>
 113   <refsect2 id="command-settings">
 114    <title>settings</title>
 115    <para>
 116     The settings command applies session-specific settings to one or more
 117     databases. A typical function of this is to enable access to
 118     restricted resources for registered users, or to set a user- or
 119     library-specific username/password to use against a target. Each
 120     setting parameter has the form name[target]=value, where name is the
 121     name of the setting (e.g. pz:authentication), target is a target ID,
 122     or possibly a wildcard, and value is the desired value for the
 123     setting.
 124    </para>
 125
 126    <para>
 127     Because the settings command manipulates potentially sensitive
 128     information, it is possible to configure Pazpar2 to only allow access
 129     to this command from a trusted site -- usually from server-side
 130     scripting, which in turn is responsible for authenticating the user,
 131     and possibly determining which resources he has access to, etc.
 132    </para>
 133
 134    <note>
 135     <para>
 136      As a shortcut, it is also possible to override settings directly in
 137      the init command.
 138     </para>
 139    </note>
 140
 141    <para>
 142     Example:
 143     <screen><![CDATA[
 144        search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
 145       ]]></screen>
 146     Response:
 147    <screen><![CDATA[
 148 <settings>
 149   <status>OK</status>
 150 </settings>
 151 ]]></screen>
 152     </para>
 153
 154   </refsect2>
 155   <refsect2 id="command-search"><title>search</title>
 156    <para>
 157     Launches a search, parameters:
 158
 159     <variablelist>
 160      <varlistentry>
 161       <term>session</term>
 162       <listitem>
 163        <para>
 164         Session ID
 165         </para>
 166       </listitem>
 167      </varlistentry>
 168      <varlistentry>
 169       <term>query</term>
 170       <listitem>
 171        <para>
 172         CCL query
 173         </para>
 174       </listitem>
 175      </varlistentry>
 176      <varlistentry>
 177       <term>filter</term>
 178       <listitem>
 179        <para>
 180         Limits the search to a given set of targets specified by the
 181         filter. The filter consists a comma separated list of
 182         setting+operator+args pairs. The setting is a Pazpar2 setting
 183         (such as <literal>pz:id</literal>).
 184         The operator is either = (string match)
 185         or ~ (substring match). The args is a list of values separated
 186         by | (or , one of the values). The idea is that only targets
 187         with a setting matching one of the values given will be included
 188         in the search.
 189        </para>
 190       </listitem>
 191      </varlistentry>
 192      <varlistentry>
 193       <term>startrecs</term>
 194       <listitem>
 195        <para>
 196         Specifies the first record to retrieve from each target.
 197         The first record in a result set for a target is numbered 0, next
 198         record is numbered 2. By default maxrecs is 0.
 199         </para>
 200       </listitem>
 201      </varlistentry>
 202      <varlistentry>
 203       <term>maxrecs</term>
 204       <listitem>
 205        <para>
 206         Specifies the maximum number of records to retrieve from each
 207         target. The default value is 100. This setting has same meaning
 208         as per-target setting pz:maxrecs . If pz:maxrecs is set, it takes
 209         precedence over argument maxrecs.
 210         </para>
 211       </listitem>
 212      </varlistentry>
 213     </variablelist>
 214
 215    </para>
 216    <para>
 217     Example:
 218     <screen><![CDATA[
 219 search.pz2?session=2044502273&command=search&query=computer+science
 220 ]]>
 221      </screen>
 222     Response:
 223    <screen><![CDATA[
 224 <search>
 225   <status>OK</status>
 226 </search>
 227      ]]></screen>
 228    </para>
 229   </refsect2>
 230
 231   <refsect2 id="command-stat">
 232    <title>stat</title>
 233    <para>
 234     Provides status information about an ongoing search. Parameters:
 235
 236     <variablelist>
 237      <varlistentry>
 238       <term>session</term>
 239       <listitem>
 240        <para>
 241         Session ID
 242         </para>
 243       </listitem>
 244      </varlistentry>
 245     </variablelist>
 246
 247    </para>
 248    <para>
 249     Example:
 250    <screen><![CDATA[
 251 search.pz2?session=2044502273&command=stat
 252     ]]></screen>
 253     Output
 254     <screen><![CDATA[
 255 <stat>
 256   <activeclients>3</activeclients>
 257   <hits>7</hits>                   -- Total hitcount
 258   <records>7</records>             -- Total number of records fetched in last query
 259   <clients>1</clients>             -- Total number of associated clients
 260   <unconnected>0</unconnected>     -- Number of disconnected clients
 261   <connecting>0</connecting>       -- Number of clients in connecting state
 262   <initializing>0</initializing>   -- Number of clients initializing
 263   <searching>0</searching>         -- ... searching
 264   <presenting>0</presenting>       -- ... presenting
 265   <idle>1</idle>                   -- ... idle (not doing anything)
 266   <failed>0</failed>               -- ... Connection failed
 267   <error>0</error>                 -- ... Error was produced somewhere
 268 </stat>
 269      ]]></screen>
 270   </para>
 271   </refsect2>
 272
 273   <refsect2 id="command-show">
 274    <title>show</title>
 275    <para>
 276     Shows records retrieved. Parameters:
 277     <variablelist>
 278      <varlistentry>
 279       <term>session</term>
 280       <listitem>
 281        <para>
 282         Session ID
 283         </para>
 284       </listitem>
 285      </varlistentry>
 286
 287      <varlistentry>
 288       <term>start</term>
 289       <listitem>
 290        <para>First record to show - 0-indexed.</para>
 291       </listitem>
 292      </varlistentry>
 293
 294      <varlistentry>
 295       <term>num</term>
 296       <listitem>
 297        <para>
 298         Number of records to show If omitted, 20 is used.
 299        </para>
 300       </listitem>
 301      </varlistentry>
 302
 303      <varlistentry>
 304       <term>block</term>
 305       <listitem>
 306        <para>
 307         If block is set to 1, the command will hang until there are records ready
 308         to display. Use this to show first records rapidly without
 309         requiring rapid polling.
 310        </para>
 311       </listitem>
 312      </varlistentry>
 313
 314      <varlistentry>
 315       <term>sort</term>
 316       <listitem>
 317        <para>
 318         Specifies sort criteria. The argument is a comma-separated list
 319         (no whitespace allowed) of sort fields, with the highest-priority
 320         field first. A sort field may be followed by a colon followed by
 321         the number '0' or '1', indicating whether results should be sorted in
 322         increasing or decreasing order according to that field. 0==Decreasing is
 323         the default. Sort field names can be any field name designated as a sort field
 324         in the pazpar2.cfg file, or the special name 'relevance'.
 325        </para>
 326       </listitem>
 327      </varlistentry>
 328
 329     </variablelist>
 330    </para>
 331    <para>
 332     Example:
 333     <screen><![CDATA[
 334 search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
 335 ]]></screen>
 336     Output:
 337     <screen><![CDATA[
 338 <show>
 339   <status>OK</status>
 340   <activeclients>3</activeclients>     -- How many clients are still working
 341   <merged>6</merged>                   -- Number of merged records
 342   <total>7</total>                     -- Total of all hitcounts
 343   <start>0</start>                     -- The start number you requested
 344   <num>2</num>                         -- Number of records retrieved
 345   <hit>
 346     <md-title>How to program a computer, by Jack Collins</md-title>
 347     <count>2</count>                   -- Number of merged records
 348     <recid>6</recid>                   -- Record ID for this record
 349   </hit>
 350   <hit>
 351     <md-title>
 352   Computer processing of dynamic images from an Anger scintillation camera :
 353   the proceedings of a workshop /
 354     </md-title>
 355     <recid>2</recid>
 356   </hit>
 357 </show>
 358      ]]></screen>
 359    </para>
 360   </refsect2>
 361
 362   <refsect2 id="command-record">
 363    <title>record</title>
 364    <para>
 365     Retrieves a detailed record. Unlike the
 366     <link linkend="command-show">show</link> command, this command
 367     returns metadata records before merging takes place. Parameters:
 368
 369     <variablelist>
 370      <varlistentry>
 371       <term>session</term>
 372       <listitem>
 373        <para>
 374         Session ID
 375        </para>
 376       </listitem>
 377      </varlistentry>
 378
 379      <varlistentry>
 380       <term>id</term>
 381       <listitem>
 382        <para>
 383         record ID as provided by the
 384         <link linkend="command-show">show</link> command.
 385         </para>
 386       </listitem>
 387      </varlistentry>
 388
 389      <varlistentry>
 390       <term>offset</term>
 391       <listitem>
 392        <para>
 393         This optional parameter is an integer which, when given, makes
 394         Pazpar2 return the raw record for a target. The raw record
 395         from first target is numbered 0, second numbered 1, etc.
 396         When a raw record is returned Pazpar2 will XSLT transform the
 397         record but an XML version is returned. All ISO2709 records are
 398         returned as MARCXML. OPAC records are returned as YAZ'
 399         OPAC with an MARCXML sibling.
 400        </para>
 401        <para>
 402         When offset is not given the Pazpar2 metadata for the record
 403         is returned and with metadata for each targets' data specified
 404         in a 'location' list.
 405        </para>
 406       </listitem>
 407      </varlistentry>
 408
 409      <varlistentry>
 410       <term>syntax</term>
 411       <listitem>
 412        <para>
 413         This optional parameter is the record syntax used for raw
 414         transfer (i.e. when offset is specified). If syntax is not given,
 415         but offset is used, the value of pz:requestsyntax is used.
 416        </para>
 417       </listitem>
 418      </varlistentry>
 419
 420      <varlistentry>
 421       <term>esn</term>
 422       <listitem>
 423        <para>
 424         This optional parameter is the element set name used to retrieval
 425         of a raw record (i.e. when offset is specified).
 426         If esn is not given, but offset is used, the value of pz:elements
 427         is used.
 428        </para>
 429       </listitem>
 430      </varlistentry>
 431
 432      <varlistentry>
 433       <term>binary</term>
 434       <listitem>
 435        <para>
 436         This optional parameter enables "binary" response for retrieval
 437         of a raw record (i.e. when offset is specified). For binary
 438         responses the record is <emphasis>not</emphasis> converted to
 439         XML and the HTTP content type is application/octet-stream.
 440        </para>
 441       </listitem>
 442      </varlistentry>
 443
 444     </variablelist>
 445    </para>
 446    <para>
 447     Example:
 448     <screen><![CDATA[
 449 search.pz2?session=605047297&command=record&id=3
 450 ]]></screen>
 451
 452     Example output:
 453
 454     <screen><![CDATA[
 455 <record>
 456   <md-title>
 457         The Puget Sound Region : a portfolio of thematic computer maps /
 458   </md-title>
 459   <md-date>1974</md-date>
 460   <md-author>Mairs, John W.</md-author>
 461   <md-subject>Cartography</md-subject>
 462 </record>
 463 ]]></screen>
 464    </para>
 465   </refsect2>
 466
 467   <refsect2 id="command-termlist">
 468    <title>termlist</title>
 469    <para>
 470     Retrieves term list(s). Parameters:
 471
 472     <variablelist>
 473      <varlistentry>
 474       <term>session</term>
 475       <listitem>
 476        <para>
 477         Session Id.
 478        </para>
 479       </listitem>
 480      </varlistentry>
 481      <varlistentry>
 482       <term>name</term>
 483       <listitem>
 484        <para>
 485         comma-separated list of termlist names (default "subject")
 486        </para>
 487       </listitem>
 488      </varlistentry>
 489     </variablelist>
 490    </para>
 491    <para>
 492     Example:
 493     <screen><![CDATA[
 494 search.pz2?session=2044502273&command=termlist&name=author,subject
 495 ]]></screen>
 496 Output:
 497     <screen><![CDATA[
 498 <termlist>
 499   <activeclients>3</activeclients>
 500   <list name="author">
 501     <term>
 502       <name>Donald Knuth</name>
 503       <frequency>10</frequency>
 504     </term>
 505       <term>
 506       <name>Robert Pirsig</name>
 507       <frequency>2</frequency>
 508     </term>
 509   </list>
 510   <list name="subject">
 511     <term>
 512       <name>Computer programming</name>
 513       <frequency>10</frequency>
 514     </term>
 515   </list>
 516 </termlist>
 517 ]]></screen>
 518     </para>
 519
 520    <para>
 521     For the special termlist name "xtargets", results
 522     are returned about the targets which have returned the most hits.
 523     The 'term' subtree has additional elements,
 524     specifically a state and diagnostic field (in the example below, a
 525     target ID is returned in place of 'name'.
 526     This may or may not change later.
 527    </para>
 528    <para>
 529     Example
 530     <screen><![CDATA[
 531 <term>
 532   <name>library2.mcmaster.ca</name>
 533   <frequency>11734</frequency>         -- Number of hits
 534   <state>Client_Idle</state>           -- See the description of 'bytarget' below
 535   <diagnostic>0</diagnostic>           -- Z39.50 diagnostic codes
 536 </term>
 537 ]]></screen>
 538     </para>
 539   </refsect2>
 540
 541
 542   <refsect2 id="command-bytarget">
 543    <title>bytarget</title>
 544    <para>
 545     Returns information about the status of each active client. Parameters:
 546
 547     <variablelist>
 548      <varlistentry>
 549       <term>session</term>
 550       <listitem>
 551        <para>
 552         Session Id.
 553         </para>
 554       </listitem>
 555      </varlistentry>
 556     </variablelist>
 557    </para>
 558    <para>
 559     Example:
 560     <screen><![CDATA[
 561 search.pz2?session=605047297&command=bytarget&id=3
 562 ]]></screen>
 563
 564     Example output:
 565
 566     <screen><![CDATA[
 567 <bytarget>
 568   <status>OK</status>
 569   <target>
 570     <id>z3950.loc.gov/voyager/</id>
 571     <hits>10000</hits>
 572     <diagnostic>0</diagnostic>
 573     <records>65</records>
 574     <state>Client_Presenting</state>
 575   </target>
 576   <!-- ... more target nodes below as necessary -->
 577 </bytarget>
 578 ]]></screen>
 579
 580     The following client states are defined: Client_Connecting,
 581     Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
 582     Client_Searching, Client_Presenting, Client_Error, Client_Failed,
 583     Client_Disconnected, Client_Stopped, Client_Continue.
 584    </para>
 585   </refsect2>
 586
 587  </refsect1>
 588  <refsect1><title>SEE ALSO</title>
 589   <para>
 590    Pazpar2:
 591    <citerefentry>
 592     <refentrytitle>pazpar2</refentrytitle>
 593     <manvolnum>8</manvolnum>
 594    </citerefentry>
 595   </para>
 596   <para>
 597    Pazpar2 Configuration:
 598    <citerefentry>
 599     <refentrytitle>pazpar2_conf</refentrytitle>
 600     <manvolnum>5</manvolnum>
 601    </citerefentry>
 602   </para>
 603  </refsect1>
 604 </refentry>
 605
 606 <!-- Keep this comment at the end of the file
 607 Local variables:
 608 mode: sgml
 609 sgml-omittag:t
 610 sgml-shorttag:t
 611 sgml-minimize-attributes:nil
 612 sgml-always-quote-attributes:t
 613 sgml-indent-step:1
 614 sgml-indent-data:t
 615 sgml-parent-document:nil
 616 sgml-local-catalogs: nil
 617 sgml-namecase-general:t
 618 End:
 619 -->