A Simple Holdings Lookup Script In Ruby

This example is intended as a counterpoint to the Simple Holdings Lookup Script providing an alternative implementation in Ruby. In addition to the numerous excellent sources on the web, Programming Ruby, The Pragmatic Programmers' Guide (more commonly known as the Ruby Pickaxe) is widely recognised as the definitive guide to the language.

Before starting you need to obtain an API Key. The API Key identifies your usage of the Talis Platform and helps us keep count of how popular the services are. You get your API Key by joining the TDN (which is free), and clicking on the "api keys" tab in your account view. Use the "request new api key" button to create new key that can be used immediately.

This script uses an open source Ruby library for parsing data in the JSON format into Ruby data structures, you can download the library from RubyForge and manually install it.

Alternatively, you could use the RubyGems package manager to download and install it. The command to do so is:

gem install json

Using RubyGems allows you to install multiple versions of a library and specify which version to use on a per-script basis.

As in the Python version, this script is intended to run as a CGI on our webserver. If you're on a UNIX based system you need a line like the following at the top of the script:

#!/usr/bin/ruby

If you're running under Windows, you might use something like:

#!c:/ruby/bin/ruby

In addition to the JSON library I mentioned above, we also require a couple of core Ruby packages, net/http and cgi so the next few lines of our script look like this:

require 'json'
require 'net/http'
require 'cgi'

The first thing to do is to output a Content-type header, so the calling program (i.e. our browser) knows how to deal with the response:

puts "Content-type: text/html\r\n\r\n"

Next, we check the inbound request for a parameter named isbn. If no isbn is supplied, we print an error message, otherwise we'll go ahead and try to fulfill the request:

c=CGI.new 
isbn=c['isbn']
if (isbn.length <= 0)
  puts "No ISBN"
else 
  puts "<p>Libraries holding copies of %s</p>" % isbn

The next step involved in handling this request is a call to the Platform bibliographic holdings lookup service which returns a list of collections that hold items matching the supplied criteria. The service URL is http://api.talis.com/1/bib/holdings and there are two parameters which are relevant for our purposes: isbn and output.

The isbn parameter denotes the ISBN of the book we want to look up and simply corresponds to our own isbn parameter. output controls the format that the holdings are returned in. For this script we're going to use the json output so the URL we will be accessing should look something like this:

http://api.talis.com/1/bib/holdings?api_key={KEY}&output=json&isbn={ISBN}

You need to replace {KEY} with your API Key. The {ISBN} value will be filled in by our script. You can try that in your browser, just insert your API Key and an ISBN like 0596006136 and point your browser at the resulting URL. This should help you to get an idea of what the JSON representation of holdings data looks like.

Here's the code that constructs the service URL (by replacing the %s placeholder with the value from the request's isbn parameter) and makes an HTTP request to the service:

url="http://api.talis.com/1/bib/holdings?api_key={KEY}&output=json&isbn=%s" %  isbn
response = Net::HTTP.get_response(URI.parse(url))

Now we use the json library to parse the response from the Platform service into a Ruby data structure. At the top level of this data structure will be a hash containing one item keyed on 'Holdings', which in turn will contain another hash keyed on the isbn supplied (this makes a little more sense when you consider that the Platform service supports the lookup of multiple isbns in a single request, if you were to lookup several isbns, this hash would contain an element keyed on each one). The isbn-keyed element contains an array of hashes, each representing a single holding for the isbn, and each with the several named elements (you can think of these as fields). The fields of interest to us are name (the name of the holding Collection) and identifier (a Platform identifier for the collection, which we'll make use of shortly)

holdings = JSON.parse(response.body)

Looping through the set of holdings is trivial, so we'll add an extra bit of Platform goodness in while we're here, we'll make use of another Platform service, bibliographic deep linking to lookup up the holding Collection's details in the directory and provide a direct link to the item in the Collection's OPAC.

As with the bibliographic holdings lookup, all we need to do to access this service is construct a simple url, it will be in the form:

http://api.talis.com/1/node/items/{ID}/bib?api_key={KEY}&isbn={ISBN}

All you need to do is substitute {ID} for a valid Platform identifier for the Collection (which you have in our data structure), {KEY} for your API key and {ISBN} for the isbn you're looking up. Again, you can try entering this url into your browser

Here's the Ruby code to iterate through the data structure, outputting the HTML links:

holdings['Holdings'][isbn].each { | collection | 
    puts '<p><a href="http://api.talis.com/1/node/items/%s/bib?api_key=12345&isbn=%s"%gt;%s</a></p>' %       
[collection['identifier'], isbn, collection['name']]
  }

The result should be a list of collections each deep linked into the page in their OPAC that represents the item we are looking for.

You can find out more about Platform services by reading the Platform reference guide and by joining in the conversation in our forum

The complete code for this example is shown below:

#!/usr/bin/ruby

require 'json'
require 'net/http'
require 'cgi'

puts "Content-type: text/html\r\n\r\n"

c=CGI.new 
isbn=c['isbn']
if (isbn.length <= 0)
  puts "No ISBN"
else 
  puts "<p>Libraries holding copies of %s</p>" % isbn

  url="http://api.talis.com/1/bib/holdings?api_key=12345&output=json&isbn=%s" %  isbn
  response = Net::HTTP.get_response(URI.parse(url))

  holdings = JSON.parse(response.body)

  holdings['Holdings'][isbn].each { | collection | 
    puts '<p><a href="http://api.talis.com/1/node/items/%s/bib?api_key=12345&isbn=%s">%s</a></p>' % 
      [collection['identifier'], isbn, collection['name']]
  }
end