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