Check that record returned in piggyback after OPAC-record request
[irspy-moved-to-github.git] / lib / ZOOM / IRSpy / WebService.pod
1
2 package ZOOM::IRSpy::WebService;
3
4 =head1 NAME
5
6 ZOOM::IRSpy::WebService - Accessing the IRSpy database as a Web Service
7
8 =head1 INTRODUCTION
9
10 Because IRSpy keeps its information about targets as ZeeRex records in
11 a Zebra database, that information is available via the SRU and SRW
12 web services.  These two services are very closely related: the former
13 REST-like, based on HTTP GET URLs, and the latter SOAP-based.  Both
14 use the same query language (CQL) and the same XML-based result
15 formats.
16
17 (In addition, Zebra provides ANSI/NISO Z39.50 services, but these are
18 not further discussed here.)
19
20 =head1 EXAMPLE
21
22 Here is a example SRU URL that accesses the IRSpy database of the live
23 system (although it will not be accessible to most clients due to
24 firewall issues.  It is broken across lines for clarity:
25
26         http://irspy.indexdata.com:8018/IR-Explain---1?
27                 version=1.1&
28                 operation=searchRetrieve&
29                 query=net.port=3950&
30                 maximumRecords=10&
31                 recordSchema=zeerex
32
33 =cut
34
35 # http://irspy.indexdata.com:8018/IR-Explain---1?version=1.1&operation=searchRetrieve&query=net.port=3950&maximumRecords=10&recordSchema=zeerex
36
37 =pod
38
39 It is beyond the scope of this document to provide a full SRU
40 tutorial, but briefly, the URL above consists of the following parts:
41
42 =over 4
43
44 =item http://irspy.indexdata.com:8018
45
46 The base-URL of the SRU server.
47
48 =item IR-Explain---1
49
50 The name of the SRU database.
51
52 =item version=1.1, operation=searchRetrieve, etc.
53
54 SRU parameters specifying the operation requested.
55
56 =back
57
58 The parameters are as follows:
59
60 =over 4
61
62 =item version=1.1
63
64 Mandatory - SRU requests must contain an explicit version identifier,
65 and Zebra supports only version 1.1.
66
67 =item operation=searchRetrieve
68
69 Mandatory - SRU requests must contain an operation.  Zebra supports
70 several, as discussed below.
71
72 =item query=net.port=3950
73
74 When the operation is C<searchRetrieve>, a query must be specified.
75 The query is always expressed in CQL (Common Query Language), which
76 Zebra's IRSpy database supports as described below.
77
78 =item maximumRecords=10
79
80 Optional.  Specifies how many records to include in a search
81 response.  When omitted, defaults to zero: the response includes a
82 hit-count but no records.
83
84 =item recordSchema=zeerex
85
86 Optional.  Specifies what format the included XML records, if any,
87 should be in.  If omitted, defaults to "dc" (Dublin Core).  Zebra's
88 IRSpy database supports several schemas as described below.
89
90 =back
91
92 =head1 SUPPORT
93
94 =head2 SUPPORTED OPERATIONS
95
96 Zebra supports the following SRU operations:
97
98 =over 4
99
100 =item explain
101
102 This operation requires no further parameters, and returns a ZeeRex
103 record describing the IRSpy database itself.
104
105 =item searchRetrieve
106
107 This is the principle operation of SRU, combining searching of the
108 database and retrieval of the records that are found.  Its behaviour
109 is specified primarily by the C<query> parameter, support for which is
110 described below, but also by C<startRecord>, C<maximumRecords> and
111 C<recordSchema>.
112
113 =item scan
114
115 This operation scans an index of the database and returns a list of
116 candidate search terms for that index, including hit-counts.  Its
117 behaviour is specified primarily by the C<scanClause> parameter, but
118 also by C<maximumTerms> and C<responsePosition>.
119
120 Here is an example SRU Scan URL:
121
122         http://irspy.indexdata.com:8018/IR-Explain---1?
123                 version=1.1&
124                 operation=scan&
125                 scanClause=dc.title=fish
126
127 This lists all words occurring in titles, in alphabetical order,
128 beginning with "fish" or, if that word does not occur in any title,
129 the word that immediately follows it alphabetically.
130
131 The C<scanClause> parameter is a tiny query, consisting only an
132 index-name, a relation (usually "=") and a term.  The supported index
133 names are the same as those listed below.
134
135 =back
136
137 =head2 CQL SUPPORT
138
139 The following CQL context sets are supported, and are recognised in
140 queries by the specified prefixes:
141
142 =over 4
143
144 =item cql
145
146 The CQL context set.
147 http://www.loc.gov/standards/sru/cql/cql-context-set.html
148
149 =item rec
150
151 The Record Metadata context set.
152 http://srw.cheshire3.org/contextSets/rec/1.1/
153
154 =item net
155
156 The Network context set.
157 http://srw.cheshire3.org/contextSets/net/
158
159 =item dc
160
161 The Dublin Core context set.
162 http://www.loc.gov/standards/sru/cql/dc-context-set.html
163
164 =item zeerex
165
166 The ZeeRex context set.
167 http://srw.cheshire3.org/contextSets/ZeeRex/
168
169 =back
170
171 Within those sets, the following indexes are supported:
172
173 =over 4
174
175 =item cql.anywhere
176
177 =item cql.allRecords
178
179 =item rec.id
180
181 =item net.protocol
182
183 =item net.version
184
185 =item net.method
186
187 =item net.host
188
189 =item net.port
190
191 =item net.path
192
193 =item dc.title
194
195 =item dc.creator
196
197 =item zeerex.numberOfRecords
198
199 =item zeerex.set
200
201 =item zeerex.index
202
203 =item zeerex.attributeType
204
205 =item zeerex.attributeValue
206
207 =item zeerex.schema
208
209 =item zeerex.recordSyntax
210
211 =item zeerex.supports_relation
212
213 =item zeerex.supports_relationModifier
214
215 =item zeerex.supports_maskingCharacter
216
217 =item zeerex.default_contextSet
218
219 =item zeerex.default_index
220
221 =back
222
223 These indexes may in general be used with all the relations
224 C<<>,
225 C<<=>,
226 C<=>,
227 C<E<gt>=>,
228 C<E<gt>>,
229 C<<E<gt>>
230 and
231 C<exact>,
232 although of course not all combinations of index and relation make
233 sense.
234 The masking characters
235 C<*>
236 and
237 C<?>
238 may be used in all appropriate circumstances, as may the
239 word-anchoring character C<^>.
240
241 Finally, sorting criteria may be specified within the query itself.
242 Since YAZ's CQL parser does not yet implement the recently approved
243 CQL 1.2 sorting extension described at
244 http://zing.z3950.org/cql/sorting.html a different scheme is used
245 involving special relation modifiers, C<sort>, C<sort-desc> and
246 C<numeric>.
247
248 When a search-term that carries either the C<sort> or C<sort-desc>
249 relation-modifier is C<or>'d with a query, the results of that query
250 are sorted according to the value associated with the specified index
251 - for example, sorted by title if the query is C<or>'d with
252 C<dc.title=/sort 0>.  In such sort-specification query terms, the term
253 itself (C<0> in this example) is the precendence of the sort-key, with
254 zero being highest.  Further less significant sort keys may also be
255 specified, using higher-valued terms.  By default, sorting is
256 lexicographical (alphabetical); however, if the additional relation
257 modified C<numeric> is also specified, then numeric sorting is used.
258
259 For example, the query:
260
261  net.host = *.edu and dc.title=^a* or net.port=/sort/numeric 0
262
263 Finds records describing services hosted in the C<.edu> domain and
264 whose titles' first words begin with the letter C<a>, and sorts the
265 results in numeric order of the port number that they run on.  And the
266 query:
267
268  net.host = *.edu or net.port=/sort/numeric 0 or net.path=/sort-desc 1
269
270 Sorts all the C<.edu>-hosted services numerically by port; and further
271 sorts each equivalence class of services running the same port
272 alphabetically, descending, by database name.
273
274 =head2 RECORD SCHEMAS
275
276 The IRSpy Zebra database supports record retrieval using the following
277 schemas:
278
279 =over 4
280
281 =item dc
282
283 Dublin Core records (title, creator, description, etc.)
284
285 =item zeerex
286
287 ZeeRex records, the definitive version of the information that drives
288 the database.  These records use an extended version of the ZeeRex 2.0
289 schema that also includes an <irspy:status> element at the end of the
290 record.
291
292 =item index
293
294 An XML format that prescribes how the record is indexed for
295 searching.  This is useful for debugging, but not likely to be very
296 exciting for casual passers-by.
297
298 =back
299
300 =head1 SEE ALSO
301
302 C<ZOOM::IRSpy>
303
304 The specifications for SRU (REST-like Web Service) at
305 http://www.loc.gov/sru
306
307 The specifications for SRW (SOAP-based Web Service) at
308 http://www.loc.gov/srw
309
310 The Z39.50 specifications at
311 http://lcweb.loc.gov/z3950/agency/
312
313 The ZeeRex specifications at
314 http://explain.z3950.org/
315
316 The Zebra database at
317 http://indexdata.com/zebra
318
319 =head1 AUTHOR
320
321 Mike Taylor, E<lt>mike@indexdata.comE<gt>
322
323 =head1 COPYRIGHT AND LICENSE
324
325 Copyright (C) 2006 by Index Data ApS.
326
327 This library is free software; you can redistribute it and/or modify
328 it under the same terms as Perl itself, either Perl version 5.8.7 or,
329 at your option, any later version of Perl 5 you may have available.
330
331 =cut
332
333 1;