1 # $Id: WebService.pod,v 1.1 2006-09-29 16:57:18 mike Exp $
3 package ZOOM::IRSpy::WebService;
7 ZOOM::IRSpy::WebService - Accessing the IRSpy database as a Web Service
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
18 (In addition, Zebra provides ANSI/NISO Z39.50 services, but these are
19 not further discussed here.)
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:
27 http://irspy.indexdata.com:3313/IR-Explain---1?
29 operation=searchRetrieve&
35 # http://irspy.indexdata.com:3313/IR-Explain---1?version=1.1&operation=searchRetrieve&query=net.port=3950&maximumRecords=10&recordSchema=zeerex
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:
44 =item http://irspy.indexdata.com:3313
46 The base-URL of the SRU server.
50 The name of the SRU database.
52 =item version=1.1, operation=searchRetrieve, etc.
54 SRU parameters specifying the operation requested.
58 The parameters are as follows:
64 Mandatory - SRU requests must contain an explicit version identifier,
65 and Zebra supports only version 1.1.
67 =item operation=searchRetrieve
69 Mandatory - SRU requests must contain an operation. Zebra supports
70 several, as discussed below.
72 =item query=net.port=3950
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.
78 =item maximumRecords=10
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.
84 =item recordSchema=zeerex
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.
94 =head2 SUPPORTED OPERATIONS
96 Zebra supports the following SRU operations:
102 This operation requires no further parameters, and returns a ZeeRex
103 record describing the IRSpy database itself.
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
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>.
120 Here is an example SRU Scan URL:
122 http://irspy.indexdata.com:3313/IR-Explain---1?
125 scanClause=dc.title=fish
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.
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.
141 =head2 RECORD SCHEMAS
143 The IRSpy Zebra database supports record retrieval using the following
150 Dublin Core records (title, creator, description, etc.)
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
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.
171 The specifications for SRU (REST-like Web Service) at
172 http://www.loc.gov/sru
174 The specifications for SRW (SOAP-based Web Service) at
175 http://www.loc.gov/srw
177 The Z39.50 specifications at
178 http://lcweb.loc.gov/z3950/agency/
180 The ZeeRex specifications at
181 http://explain.z3950.org/
183 The Zebra database at
184 http://indexdata.com/zebra
188 Mike Taylor, E<lt>mike@indexdata.comE<gt>
190 =head1 COPYRIGHT AND LICENSE
192 Copyright (C) 2006 by Index Data ApS.
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.