lib/ZOOM/IRSpy/WebService.pod

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