doc/pazpar2_protocol.xml

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
   2  "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
   3 [
   4      <!ENTITY % local SYSTEM "local.ent">
   5      %local;
   6      <!ENTITY % entities SYSTEM "entities.ent">
   7      %entities;
   8      <!ENTITY % common SYSTEM "common/common.ent">
   9      %common;
  10 ]>
  11 <!-- $Id: pazpar2_protocol.xml,v 1.2 2007-01-12 15:21:04 adam Exp $ -->
  12 <refentry id="pazpar2_protocol">
  13  <refentryinfo>
  14   <productname>Pazpar2</productname>
  15   <productnumber>&version;</productnumber>
  16  </refentryinfo>
  17  <refmeta>
  18   <refentrytitle>Pazpar2 protocol</refentrytitle>
  19   <manvolnum>7</manvolnum>
  20  </refmeta>
  21
  22  <refnamediv>
  23   <refname>pazpar2_protocol</refname>
  24   <refpurpose>The webservice protocol of Pazpar2</refpurpose>
  25  </refnamediv>
  26
  27  <refsect1><title>DESCRIPTION</title>
  28   <para>
  29    Webservice requests are any that refer to filename "search.pz2". Arguments
  30    are GET-style parameters. Argument 'command' is required and specifies
  31    command. Any request not recognized as a webservice request as described,
  32    are forwarded to the HTTP server specified in configuration.
  33    This way, the webserver can host the user interface (itself dynamic
  34    or static HTML), and AJAX-style calls can be used from JS to interact
  35    with the search logic.
  36   </para>
  37   <para>
  38    Each command is described in sub sections to follow.
  39   </para>
  40   <refsect2 id="command-init"><title>init</title>
  41    <para>
  42     Initializes a session.
  43     Returns session ID to be used in subsequent requests.
  44    </para>
  45    <para>
  46     Example:
  47     <screen>
  48      search.pz2?command=init
  49     </screen>
  50    </para>
  51    <para>
  52     Response:
  53    </para>
  54    <screen><![CDATA[
  55     <init>
  56      <status>OK</status>
  57      <session>2044502273</session>
  58     </init>
  59 ]]></screen>
  60   </refsect2>
  61
  62   <refsect2 id="command-ping"><title>ping</title>
  63    <para>
  64     Keeps a session alive. An idle session will time out after one minute.
  65     The ping command can be used to keep the session alive absent other
  66     activity.
  67     It is suggested that any browser client have a simple alarm handler which
  68     sends a ping every 50 seconds or so once a session has been initialized.
  69    </para>
  70    <para>
  71     Example:
  72     <screen><![CDATA[
  73      search.pz?command=ping&session=2044502273
  74 ]]>
  75     </screen>
  76     Response:
  77    <screen><![CDATA[
  78 <ping>
  79   <status>OK</status>
  80 </ping>
  81 ]]></screen>
  82    </para>
  83   </refsect2>
  84   <refsect2 id="command-search"><title>search</title>
  85    <para>
  86     Launches a search, parameters:
  87
  88     <variablelist>
  89      <varlistentry>
  90       <term>session</term>
  91       <listitem>
  92        <para>
  93         Session ID
  94         </para>
  95       </listitem>
  96      </varlistentry>
  97      <varlistentry>
  98       <term>query</term>
  99       <listitem>
 100        <para>
 101         CCL query
 102         </para>
 103       </listitem>
 104      </varlistentry>
 105     </variablelist>
 106
 107    </para>
 108    <para>
 109     Example:
 110     <screen><![CDATA[
 111 search.pz2?session=2044502273&command=search&query=computer
 112 ]]>
 113      </screen>
 114     Response:
 115    <screen><![CDATA[
 116 <search>
 117   <status>OK</status>
 118 </search>
 119      ]]></screen>
 120    </para>
 121   </refsect2>
 122
 123   <refsect2 id="command-stat">
 124    <title>stat</title>
 125    <para>
 126     Provides status of ongoing search. Parameters:
 127
 128     <variablelist>
 129      <varlistentry>
 130       <term>session</term>
 131       <listitem>
 132        <para>
 133         Session ID
 134         </para>
 135       </listitem>
 136      </varlistentry>
 137     </variablelist>
 138
 139    </para>
 140    <para>
 141     Example:
 142    <screen><![CDATA[
 143 search.pz2?session=2044502273&command=stat
 144     ]]></screen>
 145     Output
 146     <screen><![CDATA[
 147 <stat>
 148   <activeclients>3</activeclients>
 149   <hits>7</hits>                   -- Total hitcount
 150   <records>7</records>             -- Total number of records fetched
 151   <clients>1</clients>             -- Total number of associated clients
 152   <unconnected>0</unconnected>     -- Number of disconnected clients
 153   <connecting>0</connecting>       -- Number of clients in connecting state
 154   <initializing>0</initializing>   -- Number of clients initializing
 155   <searching>0</searching>         -- ... searching
 156   <presenting>0</presenting>       -- ... presenting
 157   <idle>1</idle>                   -- ... idle (not doing anything)
 158   <failed>0</failed>               -- ... Connection failed
 159   <error>0</error>                 -- ... Error was produced somewhere
 160 </stat>
 161      ]]></screen>
 162   </para>
 163   </refsect2>
 164
 165   <refsect2 id="command-show">
 166    <title>show</title>
 167    <para>
 168     Shows records retrieved. Parameters:
 169     <variablelist>
 170      <varlistentry>
 171       <term>session</term>
 172       <listitem>
 173        <para>
 174         Session ID
 175         </para>
 176       </listitem>
 177      </varlistentry>
 178
 179      <varlistentry>
 180       <term>start</term>
 181       <listitem>
 182        <para>First record to show - 0-indexed.</para>
 183       </listitem>
 184      </varlistentry>
 185
 186      <varlistentry>
 187       <term>num</term>
 188       <listitem>
 189        <para>
 190         Number of records to show If omitted, 20 is used.
 191        </para>
 192       </listitem>
 193      </varlistentry>
 194
 195      <varlistentry>
 196       <term>block</term>
 197       <listitem>
 198        <para>
 199         If block is set, the command will hang until there are records ready
 200         to display. Use this to show first records rapidly without
 201         requiring rapid polling.
 202        </para>
 203       </listitem>
 204      </varlistentry>
 205
 206     </variablelist>
 207    </para>
 208    <para>
 209     Example:
 210     <screen><![CDATA[
 211 search.pz2?session=2044502273&command=show&start=0&num=2
 212 ]]></screen>
 213     Output:
 214     <screen><![CDATA[
 215 <show>
 216   <status>OK</status>
 217   <activeclients>3</activeclients>
 218   <merged>6</merged>
 219   <total>7</total>
 220   <start>0</start>
 221   <num>2</num>
 222   <hit>
 223     <md-title>How to program a computer, by Jack Collins</md-title>
 224     <count>2</count> <!-- Number of merged records -->
 225     <recid>6</recid>
 226   </hit>
 227   <hit>
 228     <md-title>
 229   Computer processing of dynamic images from an Anger scintillation camera :
 230   the proceedings of a workshop /
 231     </md-title>
 232     <recid>2</recid>
 233   </hit>
 234 </show>
 235      ]]></screen>
 236    </para>
 237   </refsect2>
 238
 239   <refsect2 id="command-record">
 240    <title>record</title>
 241    <para>
 242     Retrieves a detailed record. Parameters:
 243
 244     <variablelist>
 245      <varlistentry>
 246       <term>id</term>
 247       <listitem>
 248        <para>
 249         record ID as provided by the
 250         <link linkend="command-show">show</link> command.
 251         </para>
 252       </listitem>
 253      </varlistentry>
 254     </variablelist>
 255    </para>
 256    <para>
 257     Example:
 258     <screen><![CDATA[
 259 search.pz2?session=605047297&command=record&id=3
 260 ]]></screen>
 261
 262     Example output:
 263
 264     <screen><![CDATA[
 265 <record>
 266   <md-title>
 267         The Puget Sound Region : a portfolio of thematic computer maps /
 268   </md-title>
 269   <md-date>1974</md-date>
 270   <md-author>Mairs, John W.</md-author>
 271   <md-subject>Cartography</md-subject>
 272 </record>
 273     <screen><![CDATA[
 274 ]]></screen>
 275    </para>
 276   </refsect2>
 277
 278   <refsect2 id="command-termlist">
 279    <title>termlist</title>
 280    <para>
 281     Retrieves term list(s). Parameters:
 282
 283 session
 284 name       -- comma-separated list of termlist names (default "subject")
 285
 286    </para>
 287    <para>
 288     Example:
 289     <screen><![CDATA[
 290 search.pz2?session=2044502273&command=termlist&name=author,subject
 291 ]]></screen>
 292 Output:
 293     <screen><![CDATA[
 294 <termlist>
 295   <activeclients>3</activeclients>
 296   <list name="author">
 297     <term>
 298       <name>Donald Knuth</name>
 299       <frequency>10</frequency>
 300     </term>
 301       <term>
 302       <name>Robert Pirsig</name>
 303       <frequency>2</frequency>
 304     </term>
 305   </list>
 306   <list name="subject">
 307     <term>
 308       <name>Computer programming</name>
 309       <frequency>10</frequency>
 310     </term>
 311   </list>
 312 </termlist>
 313 ]]></screen>
 314     </para>
 315
 316    <para>
 317     For the special termlist name "xtargets", results
 318     are returned about the targets which have returned the most hits.
 319     The 'term' subtree has additional elements,
 320     specifically a state and diagnostic field (in the example below, a
 321     target ID is returned in place of 'name'.
 322     This may or may not change later.
 323    </para>
 324    <para>
 325     Example
 326     <screen><![CDATA[
 327 <term>
 328   <name>library2.mcmaster.ca</name>
 329   <frequency>11734</frequency>
 330   <state>Client_Idle</state>
 331   <diagnostic>0</diagnostic>
 332 </term>
 333 ]]></screen>
 334     </para>
 335   </refsect2>
 336
 337  </refsect1>
 338 </refentry>
 339
 340 <!-- Keep this comment at the end of the file
 341 Local variables:
 342 mode: sgml
 343 sgml-omittag:t
 344 sgml-shorttag:t
 345 sgml-minimize-attributes:nil
 346 sgml-always-quote-attributes:t
 347 sgml-indent-step:1
 348 sgml-indent-data:t
 349 sgml-parent-document:nil
 350 sgml-local-catalogs: nil
 351 sgml-namecase-general:t
 352 End:
 353 -->