lib/ZOOM/IRSpy/WebService.pod

   1 # $Id: WebService.pod,v 1.1 2006-09-29 16:57:18 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 =cut
  34
  35 # http://irspy.indexdata.com:3313/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:3313
  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< 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:3313/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 I<###>
 140
 141 =head2 RECORD SCHEMAS
 142
 143 The IRSpy Zebra database supports record retrieval using the following
 144 schemas:
 145
 146 =over4
 147
 148 =item dc
 149
 150 Dublin Core records (title, creator, description, etc.)
 151
 152 =item zeerex
 153
 154 ZeeRex records, the definitive version of the information that drives
 155 the database.  These records use an extended version of the ZeeRex 2.0
 156 schema that also includes an <irspy:status> element at the end of the
 157 record.
 158
 159 =item index
 160
 161 An XML format that prescribes how the record is indexed for
 162 searching.  This is useful for debugging, but not likely to be very
 163 exciting for casual passers-by.
 164
 165 =back
 166
 167 =head1 SEE ALSO
 168
 169 C<ZOOM::IRSpy>
 170
 171 The specifications for SRU (REST-like Web Service) at
 172 http://www.loc.gov/sru
 173
 174 The specifications for SRW (SOAP-based Web Service) at
 175 http://www.loc.gov/srw
 176
 177 The Z39.50 specifications at
 178 http://lcweb.loc.gov/z3950/agency/
 179
 180 The ZeeRex specifications at
 181 http://explain.z3950.org/
 182
 183 The Zebra database at
 184 http://indexdata.com/zebra
 185
 186 =head1 AUTHOR
 187
 188 Mike Taylor, E<lt>mike@indexdata.comE<gt>
 189
 190 =head1 COPYRIGHT AND LICENSE
 191
 192 Copyright (C) 2006 by Index Data ApS.
 193
 194 This library is free software; you can redistribute it and/or modify
 195 it under the same terms as Perl itself, either Perl version 5.8.7 or,
 196 at your option, any later version of Perl 5 you may have available.
 197
 198 =cut
 199
 200 1;