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