X-Git-Url: http://lists.indexdata.com/cgi-bin?a=blobdiff_plain;f=doc%2Fpazpar2_protocol.xml;h=a6fcf26dfead9e95444753f8ce3b32892b0e58a0;hb=f9e9bf847cf81d621e4b9a7106f0dc74a1063785;hp=47314acb69bc5de2a34fc71c996505789eaf2a0d;hpb=14830963a2f89b0ce47d4b9d9549ce6a1aae3e5e;p=pazpar2-moved-to-github.git
diff --git a/doc/pazpar2_protocol.xml b/doc/pazpar2_protocol.xml
index 47314ac..a6fcf26 100644
--- a/doc/pazpar2_protocol.xml
+++ b/doc/pazpar2_protocol.xml
@@ -37,7 +37,7 @@
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.
+ in Pazpar2.
Each command is described in sub sections to follow.
@@ -48,7 +48,20 @@
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.
+ that is included in the session ID as suffix after a period (.).
+
+
+ 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.
+
+
+ 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
+ service format.
+ The posting of a service appeared in Pazpar2 version 1.2.1.
Example:
@@ -124,8 +137,10 @@
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.
+
+
+ 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.
@@ -145,7 +160,15 @@
the init command.
-
+
+
+ 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
+ settings files.
+ The posting of settings appeared in Pazpar version 1.2.1.
+
+
Example:
+
+ sort
+
+
+ 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' and
+ 'position'.
+
+
+ If not specified here or as sort-default"
+ in pazpar2.cfg, Pazpar2 will default to the built-in 'relevance' ranking.
+
+
+ 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.
+
+
+
+
+
+ mergekey
+
+
+ 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
+ mergekey="optional" 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.
+
+
+ This facility, "dynamic mergekey", appeared in Pazpar2 version
+ 1.6.31.
+
+
+
+
+
+ rank
+
+
+ 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
+ rank 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.
+
+
+ This facility, "dynamic ranking", appeared in Pazpar2 version
+ 1.6.31.
+
+
+
+
@@ -348,21 +437,69 @@ search.pz2?session=2044502273&command=stat
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.
+ 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' and
'position'.
+
+ If not specified here or as sort-default"
+ in pazpar2.cfg, pazpar2 will default to the built-in 'relevance' ranking.
+
+ 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.
+
- For targets where If pz:sortmap
+ For targets where If pz:sortmap
is defined, a sort operation will be executed (possibly including
extending the search).
-
+
+
+ mergekey
+
+
+ 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
+ mergekey="optional" 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.
+
+
+ This facility, "dynamic mergekey", appeared in Pazpar2 version
+ 1.6.31.
+
+
+
+
+
+ rank
+
+
+ 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
+ rank 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.
+
+
+ This facility, "dynamic ranking", appeared in Pazpar2 version
+ 1.6.31.
+
+
+
+
@@ -428,21 +565,56 @@ search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
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
+ binary is given in which the record is
+ fetched as "raw" from ZOOM C (raw, original 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.
+
+
+
+
+
+ checksum
+
+
+ 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
+ binary is given in which the record is
+ fetched as "raw" from ZOOM C (raw, original record).
- 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.
+
+
+ nativesyntax
+
+
+ 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).
+
+
+
+
syntax
@@ -471,9 +643,9 @@ search.pz2?session=2044502273&command=show&start=0&num=2&sort=title:1
This optional parameter enables "binary" response for retrieval
- of a raw record (i.e. when offset is specified). For binary
- responses the record is not 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.