|
 |
SMETE Search API
1. Overview
1.1 Search Requests
2. Search Request Format
2.1 Search Parameters
3. Search Results Format
3.1 Search Response
3.1 Search Response Error Codes
4. Comments
4.1 Comments and Remarks
1. Overview
The SMETE Search API is a set of Java classes and WSDL (Web Services Description Language) files describing the SMETE federated search service. The API is a SOAP (Simple Object Access Protocol) interface to searching the learning resources cataloged at the SMETE digital library. Eventually, we will make available here:
- A complete API reference describing the semantics of method calls and fields
- Sample SOAP request and response messages
- SMETE API WSDL file
- A Java servlet library, example program, and Javadoc documentation
- A simple SOAP::Lite-based Perl script
1.1 Search Requests
Search requests submit a "query" comprised of header, which contains search parameters, and an embedded IEEE/IMS Learning Object Metadata "record" that contains the description of the actual query. The idea is that search results are derived by finding the closest matching learning resources in the SMETE digital library repository of learning resources. The search can either be "boolean" in which case the search engine does a boolean "AND" of each element in the metadata to the target metadata or "fuzzy" in which case it performs a closest metadata similarity.
The details of the interactions involved with search requests are covered in the Search Request Format and Search Results Format sections of this document.
2. Search Request Format
2.1 Search Request Parameters
The search request "doSmeteSearch" is contained within a SOAP envelope. The SOAP body then contains metadata about the search and metadata about the requested search results. Much of the syntax is borrowed from the Open Archives Protocol for Metadata Harvesting (OAI PMH) to simplify the creation of tools.
Before going into the details of the fields, here is a sample SOAP envelope.
<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/1999/XMLSchema">
<SOAP-ENV:Body>
<ns1:doSmeteSearch xmlns:ns1="urn:SMETESearch"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<header>
<searchType>boolean</searchType>
<messageSize>10</messageSize>
<language>en-us</language>
<metadataFormat>
<schema>http://www.imsglobal.org/xsd/imsmd_v1p2p2.xsd</schema>
<metadataNamespace>http://www.imsglobal.org/xsd/imsmd_v1p2</metadataNamespace>
</metadataFormat>
<resumptionToken>710FE693-46E9-4002-BA94-1BE2E6218CD6</resumptionToken>
</header>
<metadata>
<lom
xmlns:ims_lom="http://www.imsglobal.org/xsd/imsmd_v1p2"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.imsglobal.org/xsd/imsmd_v1p2
http://www.imsglobal.org/xsd/imsmd_v1p2p2.xsd">
</lom>
</metadata>
</ns1:doSmeteSearch>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
|
In this example, the LOM metadata has been removed for brevity. In its place would be a properly formed LOM metadata.
The definitions of each of the search parameters in the "header" element are described below.
Element |
Definition |
| searchType | The "searchType" element indicates the type of matching algorithm to use. In this example, specifying "boolean" means that the search engine should find boolean matches, which is interpreted as compound "AND" and "==". For example, if the LOM metadata contained "mechatronics" in the general.title field and "student" in educational.intendedendusertype, then only records matching both qualifiers would be returned. The other option is "fuzzy" which uses inexact similarity measurements. |
| messageSize | The "messageSize" field indicates the number of results to return per response. If the attribute of the tag is set to "nill", e.g., <messageSize nill="true";></messageSize>, the service will return all records in a single response. |
| language | The "language" field is the language of the records in the response. At this time, only English is supported. In the future, it is intended to support responding with the metadata in other languages, such as Chinese (zh-pr). The language identification should follow the XML Language Identification specification. |
| metadataFormat | The "metadataFormat" element contains two sub-elements, "schema" and "metadataNamespace." This is the requested format of the metadata in the response and specifies the metadata element set in the "metadata" element. If the "metadataFormat" is not supported, the server will respond with "noMetadataFormats" error. |
| resumptionToken | The "resumptionToken" is used by the search client to receive the next set of results and is stateful. If the "resumptionToken" is valid, then the search service will return the next batch of records. If it is invalid or empty, the search engine re-runs the search request and begins to return results starting from the first record. A unique "resumptionToken" is given to the client by the search server whenever the complete set of search results has not yet been returned. For more information about the "resumptionToken" see the Open Archives Initiative Protocol for Metadata Harvesting Version 2 specification.
|
3. Search Results Format
3.1 Search Response Parameters
The search response from "doSmeteSearch" is nearly syntactically identical to the OAI PMH "ListRecords" response type. The main difference is that there is no per-record "header" nor are there the "responsedate" and "request" fields. Instead, the header contains the fields "results" and "errorCode". An example of a search response is shown below, again with the actual LOM record removed for brevity.
<?xml version='1.0' encoding='UTF-8'?>
<ListRecords>
<header>
<errorCode></errorCode>
<results>2</results>
</header>
<record>
<metadata>
<lom
xmlns:ims_lom="http://www.imsglobal.org/xsd/imsmd_v1p2"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.imsglobal.org/xsd/imsmd_v1p2
http://www.imsglobal.org/xsd/imsmd_v1p2p2.xsd">
</lom>
</metadata>
</record>
<record>
<metadata>
<lom
xmlns:ims_lom="http://www.imsglobal.org/xsd/imsmd_v1p2"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.imsglobal.org/xsd/imsmd_v1p2
http://www.imsglobal.org/xsd/imsmd_v1p2p2.xsd">
</lom>
</metadata>
</record>
<resumptionToken>710FE693-46E9-4002-BA94-1BE2E6218CD6</resumptionToken>
</ListRecords>
|
3.2 Search Response Error Codes
If the search request produced an error, the "doSmeteSearch" service will respond with an error code in the header. These error codes are identical to the OAI PMH Version 2 error codes with the addition of the "notAllowed" error code. At this moment, this error code will not be produced; the intent is to provide an eventual means to implement a digital rights system which will limit searches.
4. Comments
4.1 Comments and Remarks
We developed this SOAP-based SMETE Search API after a trial period of a federated search using simple HTTP GET/POST name-value pairs. What we learned through this process was the following:
- Most digital libraries have already expended considerable resources to develop parsers for writing and reading certain metadata element sets, including Dublin Core and Learning Object Metadata. They would like to leverage that investment.
- There is still no "standard" for a query language that has been widely adopted by digital libraries. Essentially, only the query and query-type standards for Z39.50 have been widely adopted by libraries, but primarily only for bibliographic retrievel. The Simple Digital Library Interoperability Protocol (SDLIP) recommended the use of the IETF DAV Searching and Locating protocol for encoding search requests. However, the IETF closed the working group due to lack of progress.
- There is still no widely-adopted standard for federated search. Most are ad-hoc. There has been some research in specification methods for describing the federated search syntax of heterogeneous federated search services, e.g. Global Federated Searcher. Nonetheless, each search service may specify its own proprietary method.
- We investigated various XML-based query languages, including most notably XQuery which is based on XPath. However, we questioned whether digital libraries would devote the resources required to implement XQuery (including the associated human resources to "get up to speed" on its use), especially for a query language that is not yet adopted as a standard and is still a moving target.
For these reasons, we opted to adopt SOAP as the communication protocol, WSDL as the mechanism to describe the search service, and existing metadata element sets and syntax for encoding the search query and the search results. Together, these form the SMETE Search API. There are already numerous open source software tools for implementing SOAP and WSDL and they appear to become official W3C standards. The popular search engine Google has proposed its own Google API for searching the Google repository using SOAP and WSDL. Thus, if digital libraries implement a SOAP client to search the SMETE collection, they will also be able to use the same code base to search the Google repository for other Web-based learning resources. Microsoft's .NET initiative also supports SOAP. We believe that this is a good strategy for implementing federated search across heterogenous collections.
|