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.
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:
- 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:
- Or a couple:
- The most recent 10 books by anyone named 'Bonk'
- And how about the next ten?
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.