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;