doc/pazpar2_protocol.xml

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