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