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