New REST-ful API for Mirlyn

June 02, 2008

Earlier this week, I had a chance to give a brown-bag session on a new API into our catalog, Mirlyn (Ex Libris's Aleph software).

One of the great things about working at a library is the depth and breadth of data at our disposal. One of the more frustrating things is how terribly locked-up all that data is.

What, I wondered, would happen if I could radically lower the bar of entry to the catalog for programmers of even marginal ability? The University of Michigan has a pretty big collection, and there's no telling what people could do with that data if getting at it was a lot easier, if they didn't need special permission or access to a particular machine, and if it was useful inside the browser using Javascript as well as in server-side operations?

So I went about trying to create a system that fulfilled, at least partially, those criteria. Unlike many ILS systems, Aleph already provides a whole suite of interfaces, including an XML-based API they call the XServer. Unfortunately, the XServer has, in my opinion, a number of shortcomings:

  • As its name suggests, it's based on XML, which can be confusing to deal with to the uninitiated. Remember, my focus is on weekend programmers, maybe just writing javascript inline in an HTML document.
  • URLs for an XServer search don't mean anything. First you do a search, and get back a search set. Then you ask for some records using that search set in the URL. It's essentially a random identifier, and looking at the URL doesn't tell you anything about what search was done or what you're getting, and you're sure not going to construct one by hand.
  • The interface is...messy. It's clearly a system that grew up organically, and there are a lot of inconsistencies concerning how things are named, what parameters are called, etc. I wanted an interface where you could take a good guess at what the URL should look like and be right 90% of the time.

When I was all done, I had a system that supports queries like this:

A book by ISBN:
http://mirlyn.lib.umich.edu/cgi-bin/api/basic.json/isbn/097669400x
Or a couple:
http://mirlyn.lib.umich.edu/cgi-bin/api/basic.json/isbn/0596000278;097669400x?records=all
The most recent 10 books by anyone named 'Bonk'
http://mirlyn.lib.umich.edu/cgi-bin/api/basic.json/author/bonk?records=1-10
And how about the next ten?
http://mirlyn.lib.umich.edu/cgi-bin/api/basic.json/author/bonk?records=11-20

You can search by title, author, keyword, most standard numbers -- just about anything you can use to search the catalog via the website. The full list of searchable indexes and their aliases, as well as all the current Mirlyn API documentation, is on the new MLibrary API wiki.

While all the above examples return a subset of available data in the JSON format, you can also return XML if you're more comfortable with it, and besides the "basic" data you can get circulation status or full MARC records (expanded into either XML or JSON). Just replace "basic.json" in the above URLs with something like "marc.xml" or "circstatus.json".

There's still a lot to do (allow user-defined sorting, let people browse by callnumber, etc.) but it works and is useful and is certainly friendly, in enough ways, that people can start digging into it if they want.

I've put some simple javascript examples on the MLibrary Labs page; check them out, and drop me a note (or, better yet, comment here!) if you have questions or ideas.

Posted by Bill Dueber at 08:51 AM. Permalink

Comments

This is great, thank you for doing this. The documentation is particularly good.

I haven't been able to get the Simple, slow sample or the Slightly less-slow sample to work on a non-Apple computer, though.

One thing I would be interested in seeing available in the API in the future is the description information for item records (I think Mirlyn calls it "Vol. : Issue" in the OPAC). This could be useful in checking the availability of, or linking to, particular volumes and issues of serials. Checking the circstatus of the Congressional Record basically gives me a list of 1300 barcode numbers:
http://mirlyn.lib.umich.edu/cgi-bin/api/circstatus.xml/journal/congressional%20record%20proceedings

With the descriptions I could conceivably offer a link to the full text of v.4 pt.6 1876, or that and other items' availability information.

Posted by: dfulmer at June 4, 2008 01:03 AM

Login to leave a comment. If you don't have already have a University of Michigan uniqname, create a Friend account -- all you need is a valid email address.