Get Tooled Up: SeeAlso: A Simple Linkserver Protocol
In recent years the principle of Service-oriented Architecture (SOA) has grown increasingly important in digital library systems. More and more core functionalities are becoming available in the form of Web-based, standardised services which can be combined dynamically to operate across a broader environment [1]. Standard APIs for searching (SRU [2] [3], OpenSearch [4]), harvesting and syndication (OAI-OMH [5], ATOM [6]), copying (unAPI [7] [8]), publishing, editing (AtomPub [9], Jangle [10], SRU Update [11]), and more basic library operations, either already exist or are being developed.
The creation of the SeeAlso linkserver protocol was occasioned by the need to enrich title views in library catalogues of the German Common Library Network (GBV) with links to additional information. However, instead of integrating those links into title records and tailoring the presentation to our specific OPAC software, we decided to create a general linkserver Web service.
Related Work
Early hypertext architectures like the Open Hypermedia Protocol (OHP) included links as first class objects stored in specific link server databases [12]. Later the World Wide Web replaced most hypertext systems although its links are untyped, point in only one direction and can easily break [13]. Meanwhile these limitations are overcome starting with backlinks in wikis, Trackback and Pingback between blogs, as well as typed links with Microformats in HTML, together with published sets of links within the Linking Open Data Project [14].
However, the concept of a link server remains relatively unknown. SPARQL [15] can be used to query any RDF data, including links, but it is far too powerful and complex for simple applications. OpenURL [16] is more useful for resolving links rather than querying them. The most promising APIs turned out to be unAPI [8] and OpenSearch Suggestions [17]; it was decided to combine them to form the SeeAlso linkserver protocol.
Figure 1: OpenSearch Suggestions in Firefox [18]
SeeAlso Specification
The design of SeeAlso was informed by two principles: first, it should be easy to use and implement and second, it should build on existing standards. Fortunately an existing and appropriate standard was soon identified in the form of OpenSearch Suggestions. The core of the SeeAlso specification – SeeAlso Simple [19] – reuses this self same standard. The rest of SeeAlso – SeeAlso Full [20] – goes on to add elements of OpenSearch and unAPI. Both specifications have been defined and implemented. The current state of development was recently presented at ECDL 2008 [21]. The current draft of SeeAlso Simple is awaiting final comments with a view to publishing it as version 1.0. SeeAlso Full still needs some work and further feedback before it can be considered as definitively finished.
Figure 2: Example of query and response in SeeAlso
SeeAlso Simple with OpenSearch Suggestions
OpenSearch Suggestions is an extension of the OpenSearch standard to return a set of search term completion suggestions for a given search term prefix [17]. Firefox has supported this extension since its version 2 and shows search results in its Search Bar (Table 1). A suggestion is returned by a search engine in JavaScript Object Notation (JSON) [22] as an array of four values. SeeAlso Simple uses the same format. A SeeAlso Simple service is queried via HTTP GET with a query parameter “id” and and optional callback parameter “callback”. In addition to search suggestions (as defined by OpenSearch Suggestions), the response includes the element “Identifier”, the value of which echoes the query parameter. The value can be normalised by the service. For instance ISBNs in different forms can be returned as canonical URIs. The elements “Descriptions” and “URIs” are mandatory. “URIs” can contain any URIs including URLs, and the response body can be wrapped by a callback method. For this reason the MIME type of the response can be “text/javascript” instead of “application/x-suggestions+json”. Figure 2 shows an example of query and response.
| Element | OpenSearch Suggestions name | Description |
| Identifier | Query String | search term as string, can be normalised |
| Labels | Completions | array of strings with link labels |
| Descriptions | Descriptions | array of strings with additional information |
| URIs | Query | URLs array of strings with link URIs |
Table 1: The four elements of a SeeAlso response
SeeAlso Full with unAPI and OpenSearch Description
The integration of services into other applications requires not only standardised APIs for access but also standardised descriptions of particular services [1]. For this reason SeeAlso Full completes SeeAlso Simple with support of an OpenSearch description document [23]. The connection between a simple SeeAlso service and its description is established via unAPI. In short, a full SeeAlso service is an unAPI server that provides at least two formats, “seealso” and “opensearchdescription”:
<formats>
<format name=“seealso” type=“text/javascript” />
<format name=“opensearchdescription”
type=“application/opensearchdescription+xml”
docs=“http://www.opensearch.org/Specifications/OpenSearch/1.1/Draft_3#OpenSearch
_description_document” />
</formats>
If you select format=seealso, a simple SeeAlso response in JSON format is returned (see Figure 2). If you select format=opensearchdescription, an OpenSearch description document is returned. The following description is returned for the SeeAlso server at http://ws.gbv.de/seealso/isbn2gbv:
<OpenSearchDescription xmlns=“http://a9.com/-/spec/opensearch/1.1/"> <ShortName>ISBN-to-GBV</ShortName> <Description>Checks whether a given ISBN is available in the GBV union catalog </Description> <Query role=“example” searchTerms=“3-447-03706-7” /> <Query role=“example” searchTerms=“1-4013-0237-8” /> <Url type="text/javascript" template="http://ws.gbv.de/seealso/isbn2gbv?id= {searchTerms}&format=seealso&callback={callback}"
/>
</OpenSearchDescription>
This simple trick avoids the limitations of unAPI, that does not define a standard method to retrieve information about a service like verb=identify in OAI-PMH or operation=explain (the other main limitations of unAPI are a missing XML namespace and returning non-200 HTTP status codes). The combination of unAPI and OpenSearch description allows it to provide automatically an additional HTML interface to any full SeeAlso service with XSLT (Figure 3).
Figure 3: HTML interface to a SeeAlso service
Usage and Examples
SeeAlso is used in the Common Library Network (GBV) to enrich catalogues with central services without having to change existing ILS and OPAC software [24]. The most popular service delivers links to German Wikipedia articles that cite a given book by ISBN. In general SeeAlso can be used to include any list of labels and/or links dynamically. Current GBV services include look-up of links to publications of a given author (identified by PND authority file number), links to the social cataloguing services LibraryThing and BibSonomy, and links to other libraries that hold a given work. More services are planned with availability information, cover images, reviews, tables of contents and other information that is not stored in the bibliographic records.
Easy Access with JavaScript
A general barrier to innovation in (digital) libraries is the lack of technical skills. After all, standards and APIs are not much help if they impose difficult additional programming. Accordingly, a SeeAlso JavaScript client library is provided to help to lower this barrier [25]. This library contains methods to query SeeAlso services and display the result in different views (comma seperated, ordered list, tag cloud, etc.). The following script queries the SeeAlso server at http://ws.gbv.de/seealso/isbn2gbv/ and displays the result as a comma-seperated list (SeeAlsoCSV) at a given HTML-div element:
<div id=“gbvlink”/>
<script type=“text/javascript”> isbn = “1-4013-0237-8”; // query id service = new SeeAlsoService(“http://ws.gbv.de/seealso/isbn2gbv/"); service.queryDisplay( isbn, “gbvlink”, new SeeAlsoCSV() ); </script>
The library also contains methods for replacing HTML tags automatically. Libraries in the GBV library network just include the JavaScript library and put tags with predefined class attributes in the HTML code of their Web interface. The following code is used to show links to German Wikipedia articles that cite a book by ISBN:
<div class=“seealso-container” style=“display:none;”> In Wikipedia: <span title=“3-7643-5826-2” class=“isbn2wikipedia seealso-csv”></span> </div>
Web services that use APIs other than SeeAlso (for instance Google Booksearch) can be wrapped and used in the same way.
Providing SeeAlso Services
To provide a SeeAlso Web service you must at least implement OpenSearch Suggestions or rather return JSON as a response to the HTTP parameter “id” (SeeAlso Simple, Figure 2). However, it is also strongly recommended to implement unAPI and the OpenSearch description document according to the SeeAlso Full specification. An open source reference implementation in Perl is available at CPAN [26]. A new SeeAlso service is created by defining a query method and optionally describing it:
#!/usr/bin/perlsub query { my $id = shift; return unless $id->valid();
my $response = SeeAlso::Response->new( $id ); # ...determine label, description, uri ... $response->add( $label, $description, $uri ); $response->add( $label, $description, $uri ); return $response;}
my $source = SeeAlso::Source->new( &query );
$source->description( “ShortName” => “MySimpleServer”, “Description” => “…” ); print SeeAlso::Server->new()->query( $source );
Further development of the server will focus on improvements in performance and on adding wrappers and examples to create SeeAlso services on top of any data source that supports SQL or SPARQL.
Conclusion
SeeAlso combines OpenSearch and unAPI to provide a simple linkserver protocol that can be used to enrich applications dynamically with additional links and similar listed items. Content delivered by a SeeAlso link server can be integrated either on the Web server or in the client browser. For the latter, a JavaScript library is provided that limits the effort to a few lines of JavaScript and/or HTML.
The Catalog Enrichment Initiative [27] lists different possible elements for enhancing library catalogues and points out that all must support item identifiers and information about the data provider. SeeAlso fulfils these requirements with the search term parameter “id” and an OpenSearch description document for each SeeAlso service. The actual use of SeeAlso is up to the individual institution: you can add links to other libraries, Wikipedia, and social cataloguing applications; you can include information about current availability, reviews, search completion suggestions, etc. The loose coupling of link server and Web application is part of a general strategy to focus on service-oriented architecture in digital libraries. The seperation of content services and display makes it possible to integrate several Web 2.0 features in library catalogues without need to change core elements of existing software.
References
- van Veen, T., “Serving Services in Web 2.0”, April 2006, Ariadne Issue 47 http://www.ariadne.ac.uk/issue47/vanveen/
- Lease Morgan, E., “An Introduction to the Search/Retrieve URL Service (SRU)”, July 2004, Ariadne Issue 40 http://www.ariadne.ac.uk/issue40/morgan/
- SRU: Search/Retrieve via URL http://www.loc.gov/standards/sru/
- OpenSearch http://www.opensearch.org/Home
- Open Archives Initiative Protocol for Metadata Harvesting (OAI-PMH) http://www.openarchives.org/OAI/openarchivesprotocol.html
- Nottingham, M., Sayre, R., “The Atom Syndication Format”, RFC 4287, December 2005 http://www.ietf.org/rfc/rfc4287.txt
- Chudnov, D. et al., “Introducing unAPI”, July 2006, Ariadne Issue 47, http://www.ariadne.ac.uk/issue48/chudnov-et-al/
- Chudnov, D. et al., “unAPI specification version 1”, June 2006 http://unapi.info/specs/
- Gregario, J. and B. de hOra, “The Atom Publishing Protocol”, RFC 5023, October 2007 http://www.ietf.org/rfc/rfc5023.txt
- Singer, R., Farrugia, J., “Unveiling Jangle: Untangling Library Resources and Exposing them through the Atom Publishing Protocol”, Code4Lib 4, September 2008 http://journal.code4lib.org/articles/109
- SRU Record update http://www.loc.gov/standards/sru/record-update/
- Michaelides, D.T., Millard, D.E., Weal, M.J., Roure, D.D., “Auld Leaky: A Contextual Open Hypermedia Link Server” 12th ACM Conference on Hypertext and Hypermedia, LNCS 2266, 2001, p. 59–70
- Ayers, D., “Evolving the Link”, IEEE Internet Computing 11(3), 2007, p. 94-96 http://dannyayers.com/docs/ieee/w3
- Linking Open Data project http://esw.w3.org/topic/SweoIG/TaskForces/CommunityProjects/LinkingOpenData
- Prud’hommeaux, E., Seaborne, A., “SPARQL Query Language for RDF”, W3C, January 2008 http://www.w3.org/TR/rdf-sparql-query/
- Van de Sompel, H., Beit-Arie, O., “Open Linking in the Scholarly Information Environment Using the OpenURL Framework”, D-Lib Magazine, 7 March 2001 http://www.dlib.org/dlib/march01/vandesompel/03vandesompel.html
- Clintin, D., “OpenSearch Suggestions 1.0”, Public draft 1.0 http://www.opensearch.org/Specifications/OpenSearch/Extensions/Suggestions
- Creating OpenSearch plugins for Firefox https://developer.mozilla.org/en/Creating_OpenSearch_plugins_for_Firefox
- SeeAlso Simple Specification http://www.gbv.de/wikis/cls/SeeAlso_Simple_Specification
- SeeAlso Full Specification http://www.gbv.de/wikis/cls/SeeAlso_Full_Specification (in progress)
- Voß, J. “Dynamic Catalogue Enrichment with SeeAlso Link Servers”, ECDL 2008, Aarhus http://eprints.rclis.org/archive/00014639/
- Crockford, D., “JavaScript Object Notation”, RFC 4627, July 2006 http://www.json.org/
- Tesler, J. et al., “OpenSearch description document”, 2005 http://www.opensearch.org/Specifications/OpenSearch/1.1
- SeeAlso Web services at GBV http://ws.gbv.de/seealso/
- SeeAlso JavaScript library http://ws.gbv.de/seealso/seealso.js
- Voß, J., “SeeAlso::Server”, CPAN http://search.cpan.org/dist/SeeAlso-Server/
- Draft File Content Element List of the Catalog Enrichment Initiative http://www.loc.gov/standards/catenrich/catenrich-elements.html
Author Details
Licence: This article is available under the Creative Commons Attributions-Share Alike 2.5 Generic licence (by-sa): http://creativecommons.org/licenses/by-sa/2.5/