<?xml version="1.0" standalone="no"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
- "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
+ "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
[
<!ENTITY % local SYSTEM "local.ent">
%local;
<refentryinfo>
<productname>Pazpar2</productname>
<productnumber>&version;</productnumber>
+ <orgname>Index Data</orgname>
</refentryinfo>
<refmeta>
<refentrytitle>Pazpar2 protocol</refentrytitle>
<manvolnum>7</manvolnum>
+ <refmiscinfo class="manual">Conventions and miscellaneous</refmiscinfo>
</refmeta>
<refnamediv>
<refpurpose>The webservice protocol of Pazpar2</refpurpose>
</refnamediv>
- <refsect1><title>DESCRIPTION</title>
+ <refsect1>
+ <title>DESCRIPTION</title>
<para>
Webservice requests are any that refer to filename "search.pz2". Arguments
are GET-style parameters. Argument 'command' is always required and specifies
request is forwarded to the HTTP server specified in the configuration
using the proxy setting.
This way, a regular webserver can host the user interface (itself dynamic
- or static HTML), and Ajax-style calls can be used from JS (or any other client-based
- scripting environment) to interact with the search logic in Pazpar2.
+ or static HTML), and Ajax-style calls can be used from JS (or any other
+ client-based scripting environment) to interact with the search logic
+ in Pazpar2.
</para>
<para>
Each command is described in sub sections to follow.
</para>
- <refsect2 id="command-init"><title>init</title>
+ <refsect2 id="command-info">
+ <title>info</title>
+ <para>
+ Returns version and statistics about the Pazpar2 instance.
+ </para>
+ </refsect2>
+ <refsect2 id="command-init">
+ <title>init</title>
<para>
Initializes a session.
Returns session ID to be used in subsequent requests. If
- a server ID is given in the Pazpar2 server section, then a
- period (.) and the server ID is appended to the session ID.
+ a server ID is given in the Pazpar2 server section, then
+ that is included in the session ID as suffix after a period (.).
+ </para>
+ <para>
+ If the init command is performed as a HTTP GET request, service
+ and settings from local files are used. The service parameter
+ may chose a particular local service.
+ </para>
+ <para>
+ If the init command is performed as a HTTP POST request and
+ the content-type is text/xml, then the content is XML parsed
+ and treated as service for the session. The root element should be
+ service. Refer to descripton of the
+ <link linkend="service_conf">service</link> format.
+ The posting of a service appeared in Pazpar2 version 1.2.1.
</para>
<para>
Example:
</init>
]]></screen>
<para>
- The init command may take a number of setting parameters, similar to
- the 'settings' command described below. These settings are immediately
- applied to the new session. Other parameters for init are:
+ The init command may take a number of setting parameters, similar to
+ the 'settings' command described below. These settings are immediately
+ applied to the new session. Other parameters for init are:
<variablelist>
<varlistentry>
<term>clear</term>
</variablelist>
</para>
</refsect2>
-
- <refsect2 id="command-ping"><title>ping</title>
+
+ <refsect2 id="command-ping">
+ <title>ping</title>
<para>
Keeps a session alive. An idle session will time out after one minute.
The ping command can be used to keep the session alive absent other
The settings command applies session-specific settings to one or more
databases. A typical function of this is to enable access to
restricted resources for registered users, or to set a user- or
- library-specific username/password to use against a target. Each
- setting parameter has the form name[target]=value, where name is the
+ library-specific username/password to use against a target.
+ </para>
+ <para>
+ Each setting parameter has the form name[target]=value, where name is the
name of the setting (e.g. pz:authentication), target is a target ID,
or possibly a wildcard, and value is the desired value for the
setting.
</para>
-
+
<para>
Because the settings command manipulates potentially sensitive
information, it is possible to configure Pazpar2 to only allow access
scripting, which in turn is responsible for authenticating the user,
and possibly determining which resources he has access to, etc.
</para>
-
+
<note>
<para>
As a shortcut, it is also possible to override settings directly in
the init command.
</para>
</note>
-
+
+ <para>
+ If the settings command is performed as HTTP POST and the content-type
+ is text/xml, then the content is XML parsed and treated as settings -
+ with a format identical to local
+ <link linkend="target_settings">settings files</link>.
+ The posting of settings appeared in Pazpar version 1.2.1.
+ </para>
+
<para>
Example:
<screen><![CDATA[
- search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
+search.pz?command=settings&session=2044502273&pz:allow[search.com:210/db1]=1
]]></screen>
Response:
<screen><![CDATA[
<status>OK</status>
</settings>
]]></screen>
- </para>
+ </para>
</refsect2>
- <refsect2 id="command-search"><title>search</title>
+ <refsect2 id="command-search">
+ <title>search</title>
<para>
Launches a search, parameters:
-
+
<variablelist>
<varlistentry>
<term>session</term>
<listitem>
<para>
Limits the search to a given set of targets specified by the
- filter. The filter consists a comma separated list of
- setting+operator+args pairs. The setting is a Pazpar2 setting
+ filter. The filter consists of a comma separated list of
+ <emphasis>setting</emphasis>+<emphasis>operator</emphasis>+<emphasis>args</emphasis>
+ pairs. The <emphasis>setting</emphasis> is a Pazpar2 setting
(such as <literal>pz:id</literal>).
- The operator is either = (string match)
- or ~ (substring match). The args is a list of values separated
- by | (or , one of the values). The idea is that only targets
- with a setting matching one of the values given will be included
- in the search.
+ The <emphasis>operator</emphasis> is either
+ <literal>=</literal> (string match)
+ or <literal>~</literal> (substring match).
+ The <emphasis>args</emphasis> is a list of values separated
+ by <literal>|</literal> (or , one of the values).
+ The idea is that only targets with a setting matching one of
+ the values given will be included in the search.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>limit</term>
+ <listitem>
+ <para>
+ Narrows the search by one or more fields (typically facets).
+ The limit is sequence of one or more
+ <emphasis>name</emphasis>=<emphasis>args</emphasis> pairs separated
+ by comma. The <emphasis>args</emphasis> is a list of values
+ separated by vertical bar (<literal>|</literal>).
+ The meaning of <literal>|</literal> is alternative, ie OR .
+ A value that contains a comma (<literal>,</literal>),
+ a vertical bar (<literal>|</literal>) or
+ backslash itself must be preceded by backslash (<literal>\</literal>).
+ The <link linkend="limitmap">pz:limitmap</link> configuration
+ item defines how the searches are mapped to a database.
</para>
</listitem>
</varlistentry>
<para>
Specifies the first record to retrieve from each target.
The first record in a result set for a target is numbered 0, next
- record is numbered 2. By default maxrecs is 0.
+ record is numbered 1. By default startrecs is 0.
</para>
</listitem>
</varlistentry>
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>sort</term>
+ <listitem>
+ <para>
+ Specifies sort criteria. The argument is a comma-separated list
+ (no whitespace allowed) of sort fields, with the highest-priority
+ field first. A sort field may be followed by a colon followed by
+ the number '0' (decreasing) or '1' (increasing). Default
+ sort order is decreasing.
+ Sort field names can be any field name designated as a sort field
+ in the pazpar2.cfg file, or the special names 'relevance',
+ 'retrieval' and 'position'.
+ </para>
+ <para>
+ Sort type 'position' sorts by position/offset for each database.
+ Sort type 'retrieval' sorts by position of retrieval (first record
+ retrieved is 1, second record is 2, etc.).
+ </para>
+ <para>
+ If not specified here or as
+ <link linkend="sort-default">sort-default"</link>
+ in pazpar2.cfg, Pazpar2 will default to the built-in
+ 'relevance' ranking.
+ </para>
+ <para>
+ Having sort criteria at search is important for targets that
+ supports native sorting in order to get best results. Pazpar2
+ will trigger a new search if search criteria changes from Pazpar2
+ to target-based sorting or visa-versa.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>mergekey</term>
+ <listitem>
+ <para>
+ Sets mergekey for this search and rest of session, or until
+ another mergekey is given for show/search. The mergekey value is a
+ comma separated list with one or more names as they appear
+ in the service description equivalent to
+ <literal>mergekey="optional"</literal> inside a metadata element.
+ If the empty string is given for mergekey it is disabled
+ and rest of session will use the default mergekey from service
+ or stylesheet.
+ </para>
+ <para>
+ This facility, "dynamic mergekey", appeared in Pazpar2 version
+ 1.6.31.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>rank</term>
+ <listitem>
+ <para>
+ Sets rank method this search and rest of session, or until
+ another rank is given for show/search. The rank value is a
+ comma separated list of pairs field=value pairs. The
+ format is the same as
+ <xref linkend="metadata-rank">rank</xref> for a metadata element.
+ If the empty string is given for rank it is disabled
+ and rest of session will use the default rank from metadata or
+ stylesheet.
+ </para>
+ <para>
+ This facility, "dynamic ranking", appeared in Pazpar2 version
+ 1.6.31.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</para>
]]></screen>
</para>
</refsect2>
-
+
<refsect2 id="command-stat">
<title>stat</title>
<para>
]]></screen>
</para>
</refsect2>
-
+
<refsect2 id="command-show">
<title>show</title>
<para>
<listitem>
<para>
Session ID
- </para>
+ </para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>start</term>
<listitem>
<para>First record to show - 0-indexed.</para>
</listitem>
</varlistentry>
-
+
<varlistentry>
<term>num</term>
<listitem>
<term>block</term>
<listitem>
<para>
- If block is set to 1, the command will hang until there are records ready
- to display. Use this to show first records rapidly without
+ If block is set to 1, the command will hang until there are records
+ ready to display. Use this to show first records rapidly without
requiring rapid polling.
</para>
+ <para>
+ If block is set to <literal>preferred</literal>, the command will
+ wait until records have been received from all databases with preferred
+ setting
+ </para>
</listitem>
</varlistentry>
Specifies sort criteria. The argument is a comma-separated list
(no whitespace allowed) of sort fields, with the highest-priority
field first. A sort field may be followed by a colon followed by
- the number '0' or '1', indicating whether results should be sorted in
- increasing or decreasing order according to that field. 0==Decreasing is
- the default. Sort field names can be any field name designated as a sort field
- in the pazpar2.cfg file, or the special name 'relevance'.
+ the number '0' (decreasing) or '1' (increasing). Default
+ sort order is decreasing.
+ Sort field names can be any field name designated as a sort field
+ in the pazpar2.cfg file, or the special names 'relevance',
+ 'retrieval' and 'position'.
+ </para>
+ <para>
+ Sort type 'position' sorts by position/offset for each database.
+ Sort type 'retrieval' sorts by position of retrieval (first record
+ retrieved is 1, second record is 2, etc.).
+ </para>
+ <para>
+ If not specified here or as
+ <link linkend="sort-default">sort-default"</link>
+ in pazpar2.cfg, pazpar2 will default to the built-in
+ 'relevance' ranking.
+ </para>
+ <para>
+ Having sort criteria at search is important for targets that
+ supports native sorting in order to get best results. pazpar2
+ will trigger a new search if search criteria changes from pazpar2
+ to target-based sorting.
+ </para>
+ <para>
+ For targets where If <link linkend="pzsortmap">pz:sortmap</link>
+ is defined, a sort operation will be executed (possibly including
+ extending the search).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>mergekey</term>
+ <listitem>
+ <para>
+ Sets mergekey for this show and rest of session, or until
+ another mergekey is given for show/search. The mergekey value is a
+ comma separated list with one or more names as they appear
+ in the service description equivalent to
+ <literal>mergekey="optional"</literal> inside a metadata element.
+ If the empty string is given for mergekey it is disabled
+ and rest of session will use the default mergekey from service
+ or stylesheet.
+ </para>
+ <para>
+ This facility, "dynamic mergekey", appeared in Pazpar2 version
+ 1.6.31.
</para>
</listitem>
</varlistentry>
-
+
+ <varlistentry>
+ <term>rank</term>
+ <listitem>
+ <para>
+ Sets rank method this show and rest of session, or until
+ another rank is given for show/search. The rank value is a
+ comma separated list of pairs field=value pairs. The
+ format is the same as
+ <xref linkend="metadata-rank">rank</xref> for a metadata element.
+ If the empty string is given for rank it is disabled
+ and rest of session will use the default rank from metadata or
+ stylesheet.
+ </para>
+ <para>
+ This facility, "dynamic ranking", appeared in Pazpar2 version
+ 1.6.31.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>snippets</term>
+ <listitem>
+ <para>
+ If specified and set to 1 data will include snippets marked
+ with <match> tags. Otherwise snippets will not be included.
+ </para>
+ <para>
+ This facility, "snippets", appeared in Pazpar2 version
+ 1.6.32.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</para>
<para>
<num>2</num> -- Number of records retrieved
<hit>
<md-title>How to program a computer, by Jack Collins</md-title>
- <count>2</count> -- Number of merged records
+ <count>2</count> -- Number of merged records
<recid>6</recid> -- Record ID for this record
</hit>
<hit>
<refsect2 id="command-record">
<title>record</title>
<para>
- Retrieves a detailed record. Unlike the
- <link linkend="command-show">show</link> command, this command
+ Retrieves a detailed record. Unlike the
+ <link linkend="command-show">show</link> command, this command
returns metadata records before merging takes place. Parameters:
<variablelist>
<listitem>
<para>
This optional parameter is an integer which, when given, makes
- Pazpar2 return the raw record for a target. The raw record
- from first target is numbered 0, second numbered 1, etc.
- When a raw record is returned Pazpar2 will XSLT transform the
- record but an XML version is returned. All ISO2709 records are
- returned as MARCXML. OPAC records are returned as YAZ'
- OPAC with an MARCXML sibling.
+ Pazpar2 return the original record for a specific target.
+ The record set from first target is numbered 0,
+ second record set is numbered 1, etc.
+ The nativesyntax setting, as usual, is used to determine how to
+ create XML from the original record - unless parameter
+ <literal>binary</literal> is given in which the record is
+ fetched as "raw" from ZOOM C (raw, original record).
+ </para>
+ <para>
+ When offset/checksum is not given, the Pazpar2 metadata for the record
+ is returned and with metadata for each targets' data specified
+ in a 'location' list.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>checksum</term>
+ <listitem>
+ <para>
+ This optional parameter is a string which, when given, makes
+ Pazpar2 return the original record for a specific target. The
+ checksum is returned as attribtue 'checksum' in element
+ 'location' for show command and record command (when checksum
+ and offset is NOT given).
+ The nativesyntax setting, as usual, is used to determine how to
+ create XML from the original record - unless parameter
+ <literal>binary</literal> is given in which the record is
+ fetched as "raw" from ZOOM C (raw, original record).
</para>
<para>
- When offset is not given the Pazpar2 metadata for the record
+ When offset/checksum is not given, the Pazpar2 metadata for the record
is returned and with metadata for each targets' data specified
in a 'location' list.
</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term>nativesyntax</term>
+ <listitem>
+ <para>
+ This optional parameter can be used to override pz:nativesyntax
+ as given for the target. This allow an alternative nativesyntax
+ to be used for original records (see parameteroffset above).
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>syntax</term>
<listitem>
<para>
- This optional parameter is the record syntax used for raw
+ This optional parameter is the record syntax used for raw
transfer (i.e. when offset is specified). If syntax is not given,
but offset is used, the value of pz:requestsyntax is used.
</para>
<listitem>
<para>
This optional parameter enables "binary" response for retrieval
- of a raw record (i.e. when offset is specified). For binary
- responses the record is <emphasis>not</emphasis> converted to
- XML and the HTTP content type is application/octet-stream.
+ of a original record (i.e. when offset is specified). For binary
+ response the record by default is fetched from ZOOM C using
+ the "raw" option or by parameter nativesyntax if given.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>snippets</term>
+ <listitem>
+ <para>
+ If specified and set to 1 data will include snippets marked
+ with <match> tags. Otherwise snippets will not be included.
+ </para>
+ <para>
+ This facility, "snippets", appeared in Pazpar2 version
+ 1.6.32.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
- <para>
+ <para>
Example:
<screen><![CDATA[
search.pz2?session=605047297&command=record&id=3
]]></screen>
Example output:
-
+
<screen><![CDATA[
<record>
<md-title>
</para>
</refsect2>
+ <refsect2 id="command-stop">
+ <title>stop</title>
+ <para>
+ Makes Pazpar2 stop further search & retrieval for busy databases.
+ </para>
+ </refsect2>
+
<refsect2 id="command-termlist">
<title>termlist</title>
<para>
Retrieves term list(s). Parameters:
-
+
<variablelist>
<varlistentry>
<term>session</term>
<term>name</term>
<listitem>
<para>
- comma-separated list of termlist names (default "subject")
+ comma-separated list of termlist names. If omitted,
+ all termlists are returned.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>num</term>
+ <listitem>
+ <para>
+ maximum number of entries to return - default is 15.
</para>
</listitem>
</varlistentry>
<screen><![CDATA[
search.pz2?session=2044502273&command=termlist&name=author,subject
]]></screen>
-Output:
+ Output:
<screen><![CDATA[
<termlist>
<activeclients>3</activeclients>
</list>
</termlist>
]]></screen>
- </para>
+ </para>
<para>
For the special termlist name "xtargets", results
<diagnostic>0</diagnostic> -- Z39.50 diagnostic codes
</term>
]]></screen>
- </para>
+ </para>
</refsect2>
</varlistentry>
</variablelist>
</para>
- <para>
+ <para>
Example:
<screen><![CDATA[
search.pz2?session=605047297&command=bytarget&id=3
]]></screen>
Example output:
-
+
<screen><![CDATA[
<bytarget>
<status>OK</status>
<target>
- <id>z3950.loc.gov/voyager/</id>
+ <id>lx2.loc.gov/LCDB/</id>
<hits>10000</hits>
<diagnostic>0</diagnostic>
<records>65</records>
<!-- ... more target nodes below as necessary -->
</bytarget>
]]></screen>
-
+
The following client states are defined: Client_Connecting,
Client_Connected, Client_Idle, Client_Initializing, Client_Searching,
Client_Searching, Client_Presenting, Client_Error, Client_Failed,
</para>
</refsect2>
+ <refsect2 id="command-service">
+ <title>service</title>
+ <para>
+ Returns service definition (XML). Parameters:
+ <variablelist>
+ <varlistentry>
+ <term>session</term>
+ <listitem>
+ <para>
+ Session ID
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <para>
+ The service command appeared in Pazpar2 version 1.6.32
+ </para>
+ </refsect2>
</refsect1>
- <refsect1><title>SEE ALSO</title>
+ <refsect1>
+ <title>SEE ALSO</title>
<para>
Pazpar2:
<citerefentry>
<!-- Keep this comment at the end of the file
Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-local-catalogs: nil
-sgml-namecase-general:t
+mode: nxml
+nxml-child-indent: 1
End:
-->
projects / pazpar2-moved-to-github.git / blobdiff