Tech Blog

Using the IA Book Reader with Alma

In a previous blog post we demonstrated the ability to access files stored in Alma via a custom viewer. This allows for a user experience best suited to a particular type of digital material. In this post we’ll show how to use the Internet Archive Book Reader to display a digitized book stored in Alma.

About the reader

The Book Reader was developed by the Internet Archive to provide online access to scanned and digitized books. Its basic features include single and two page views, zoom, and page progression. Examples of deployments of the book reader are available on their home page.

IA Book Reader for Alma

The IA Book Reader for Alma is an adaptation of the demo code available in the Book Reader Github repository. The book reader was initially developed to support the rendering of images stored on the server. This implementation utilizes support for client side population of the book details.

Node Proxy

The book reader is a client side JavaScript application which can operate entirely in the browser. The Alma book reader uses data retrieved from Alma REST API calls to populate the reader. The client side application cannot call the Alma APIs directly due to restrictions on cross origin web requests.

We need a server side component which will retrieve the information from Alma and provide it to the book reader. Instead of a heavy web application which implements a controller for each API method, we’ve created a simply proxy in Node.js. The proxy intercepts any request made to a certain path and sends the request to Alma. It then proxies the response back to the client.

In an alma-proxy.js file, we first create an instance of the http-proxy package with some configuration options:

var apiProxy = httpProxy.createProxyServer({
   ignorePath: true,
   changeOrigin: true

Then we export a method which determines the intended Alma API path, adds an authorization header, and forwards the request to Alma. The response is sent back to the client.

exports.proxy = function(req, res) {
   // Support GET /bibs only
   var regexp = /alma(\/bibs[\/?].*)/;
   var url = regexp.exec(req.url)[1];
   apiProxy.web(req, res,
      target: nconf.get('alma_host') +
      headers: {
         "Authorization": "apikey " + nconf.get('api_key'),
         "Accept": "application/json"

Finally, we add a route to our app.js file instructing Express to send any requests which begin with alma/ to the proxy.

app.get("/alma/*", function(req, res) {
   almaProxy.proxy(req, res)

Note: This approach opens a pipe to your Alma APIs. Be sure to use a key with read only permissions or apply other safety measures before deploying this solution to a publicly available website.

Prepare the Representation

In order to be displayed in the book reader, the representation should consist of one image per page. If viewed in the Alma viewer, the representation appears as in the image below.

Book Reader Files

The remainder of the book reader application is static and therefore is placed in the public folder of the Node application. There are three files:

  • index.html- loads the various JavaScript and CSS files and provides the frame for the book reader
  • BookReaderAlma.js- performs the limited logic required to load the files from Alma
  • BookReaderAlma.css- minor style overrides

The BookReader directory contains a clone of the folder with the same name from the IA Book Reader repository.

The BookReaderAlma.js file does the following:

  • Extracts the representation PID from the query string
  • Calls the retrieve BIBs API with the representation ID and view=brief parameters to get basic bibliographic information
  • Calls the retrieve files API to get the files for the specified representation. We include the expand=url parameter to receive signed URLs for each file
  • Retrieves the height and width of the first page
  • Initializes the book reader with the required interface and the data retrieved from the API calls

That’s all there is to it. With a small bit of client-side code we’re able to implement an impressive viewer for scanned books stored in Alma.

A sample of this implementation is available here. And while we’re at it, here’s a sample implementation of the LightGallery JQuery viewer using the same methodology.

The code used in this article is available in this Github repository.

Leave a Reply