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