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