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