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