(Codenamed PatREST in my SVN)

When last I wrote about this, it was little more than a working proof-of-concept, but I’ve been working on it a lot this week–partly driven by DaveyP’s experiments and Ed’s tinkering, but mostly because I’ve been planning to do this for a long time now.

So, to cut to the chase:
PatREST now provides an easy, RESTful URI to do searches on quite a few fields. Essentially, you will plug the search key into the URI, followed by the search term. You can also request optional paging for keyword, author searches by appending hits-per-page and page-# to the URI. It looks like this:

http://www.aadl.org/rest/search/[searchkey]/[searchterm]/[hits-per-page]/[page-#]

The following search keys are available:

title
author
callnum
keyword
subject
gvtdocnum
stdnum (ISBN/ISSN)
titlekey
controlnum
barcode
record (Bib #)
bibnum (Bib # - Same as record)
itemnum

Go ahead and try this keyword search. It’ll look something like this:

You’ll notice that the XSLT stylesheet presents it nicely, all the data may not be displayed, but the XML is sound. Go ahead and view source to examine the schema. I’ve departed quite a bit from my original schema in order to provide a little bit of metadata for processing purposes. The XSLT allows you to click on a title which will take you to another RESTful record:

You’ll notice that the URI for this record looks like /rest/record/1035670/ … It’s /rest/record/[bibnum]/. The XSLT allows you to click on either the title or cover image to go to the regular OPAC record. Again, view source for the XML schema. This schema has changed little and you’ll notice that I’m taking advantage of OCLC’s xISBN service.

The real treat in all this, however, is the ability to access your personal records RESTfully. To do this, I make use of the RSS token that is provided to every cardholder who has registered for an online account. This is the token that authenticates RSS readers against our system. It is a 32 character MD5 hash that looks something like “316928e0d260556eaccb6627f2ed657b”. Accessing personal data is as easy as using the following URIs:

For checkouts, you would use /rest/checkouts/[token] (ie http://www.aadl.org/rest/checkouts/316928e0d260556eaccb6627f2ed657b). You’ll then get output at looks something like:

For holds, the URI is /rest/holds/[token]. Output looks like:

Both of those results allow you to click on the bibnum and access the REST record for that item. Again, check the XML schema with your browser (no point in putting it here).

Please hack away at this and send me your comments/suggestions. You’re absolutely correct that it doesn’t adhere to any existing standard, but that’s because I didn’t want it to.

On a slightly less geek-oriented note…

I’ve gone several rounds with Talis’s Richard Wallis before, so I want to call your attention to a post he made the other day in which he suggest that a) DaveyP and I collaborate and b) I/we consider using industry standards. I’d like to respond by saying that Dave and I have been communicating extensively. Ed Vielmetti has been involved as well.

Richard writes:

I encourage John, Dave, and those that follow them to take a look at these standards like we have

I can’t speak for Dave, but I’m very familiar with these standards and so is Ed. I think Richard is completely missing the point of this whole project which is to put a friendly, accessible, and useful development interface into the hands of patrons. Ed offers just a small example of the type of features that existing standards don’t readily make available:

Already there is a lot more useful function in it than you can get in SRU, e.g. permalinks for card records and a sensible way to get item availability.

Bear in mind, that comment was made prior to my work with RESTful holds and checkouts, which, as far as I know, don’t even have a standard XML schema–I don’t think it’s been done before! (I’d love to be corrected on this) This project will also evolve to the point where holds can be placed RESTfully, items renewed, fines paid. It’ll also extend to our other features like checkout history, wifi device management, personal card catalog management. Adding this functionality is not only going to allow the public to develop highly useful applications, but it’ll be a framework by which we ourselves can build new services in-house. Vendor’s obviously haven’t stepped up to this, so we are–and we believe in our patrons. They deserve this kind of access to their public library.

I got a lot of positive feedback concerning the virtual card catalog I put together last week. Among other things, I received a request for the ability to share your Personal Card Catalog in the same spirit of Library Thing. I thought that was a great idea, so here it is.

Anyone who has a valid user account at www.aadl.org can create a Personal Card Catalog (you do not need to be an AADL cardholder, so anyone can try it out!). Once you’ve added some cards to your own catalog, you can then go to your preferences and enable sharing:

After you’ve done that, anyone can head on over to http://www.aadl.org/pcc/(your user name). Feel free to check out mine (not much in it yet). Of course, privacy is king for all this which is why the service is opt-in with the default off. It’s not that hard to go ahead and enable it, though.

I’m going to use this service as the subject for a very unofficial study in the efficacy and popularity of Web 2.0/L2 tools. Obviously I will get statistics from database usage, number of records, queries, etc. I want to get a handle on just how useful and meaningful tools like this really are. I’ll definitely share what I find, so stay tuned!.

While working on the virtual card catalog, I ran into some serious issues with the way my xmlopac class was dealing with III’s malformed XML (sound familiar?). Again, it all comes back to the fact that III’s XML output claims to be UTF-8, but in reality, it is no such thing. These problems have also been plaguing our users who would often complain of missing titles, authors, etc.

Every time this crops up, I’ve fixed the problem, but it’s sort of like putting your finger in the dike–another leak springs up somewhere else. Anyway, the 1.9 update goes a long way toward applying a broader fix to those problems. I’d recommend that anyone who is currently using this class to update because it’ll greatly improve your results.

Ever get nostalgic for the old card catalog?

I was lurking on #code4lib and someone dropped a link to some fabulous old catalog cards. That reminded me of an idea Eli Neiburger had to make a flash-based card catalog that you could flip through. Never one to let a good idea sit, I decided to work on a variation that would allow visitors to AADL’s catalog a chance to get their hands on a “virtual card catalog”.

Thanks to some handy photoshopping by Eric Klooster, I had some really great card-stock to work with. These have some real character! Here’s one:

Using PHP’s great GD front-end, I threw together an interface to view the cards and a little database that will allow users to add some marginalia. Of course, you can view the cards with or without the comments. Here’s a one with the comments disabled:

The background stock randomly rotates, as well as the handwriting font, so you can get some really neat-looking, unique cards:

Adding a little graffiti is just a matter of typing it in:

An unlimited number of comments can be added for each “position” on the card. They are simply randomly picked from the database and drawn on the image dynamically at render time.

Users can access these via the hitlist now, and soon via the item record itself. Also, I’m working on a way for registered users to save cards in a “personal card catalog”. That way, if they see card they like, they can revisit it later.

I’m sure the layout on these cards is far from orthodox, but they’re still kinda fun. Take a look and play around. Who says the OPAC can’t be fun?

[update 1/20/2006 2:15 PM]

I’ve added the ability for registered users to “collect” cards in their own personal card catalog. Users will then be able to go to their catalog and view the cards they saved (It saves the card exactly how it was. That is, it preserves the same background, fonts, etc). Per Ed’s request, users can also email their cards to friends and co-workers with an optional note.

This is a sample card with the “Add this card to your collection” link:

And this is what the Personal Card Catalog looks like. Notice that each card is thumb-nailed–even the comments:

Obviously, I need to do a little work on the personal card catalog, allowing users to filter, sort, search, etc. But this is a start.

[/update]

After a somewhat restful day… (groan)

In an effort to make the AADL catalog a little more accessible to developers, I’ve written a little bit of middleware that generates REST output from the catalog. Yes, we currently have RSS feeds directly from the catalog, but they are not suited for true development. REST output will allow developers to freely access both hitlist data and bibliographical data without having to do any funky scraping, parsing, or wand-waving.

Please take a look, hack away, try to break it, whatever. Beta testers are always welcome!

Here are the details:

If you were to do a keyword search for “Harry Potter” on our catalog, you would see the URI looking like this:

http://www.aadl.org/cat/seek/search/X?Harry%20Potter&searchscope=26&m=&SORT=D

That, of course, is the hitlist. You want RESTful output. So change the URI to:

http://www.aadl.org/cat/rest/search/X?Harry%20Potter&searchscope=26&m=&SORT=D

Basically, you are just changing “seek” to “rest”. The base URI for the REST interface is http://www.aadl.org/cat/rest/ but going there without a query won’t get you much. Anyway, the output from the preceding looks like:

<?xml version="1.0"?>
<p:Records xmlns:p="http://www.aadl.org"
           xmlns:xlink="http://www.w3.org/1999/xlink">
	<Record id = "1249810" xlink:href="http://www.aadl.org/cat/rest/record/1249810"/>
	<Record id = "1251743" xlink:href="http://www.aadl.org/cat/rest/record/1251743"/>
	<Record id = "1239167" xlink:href="http://www.aadl.org/cat/rest/record/1239167"/>
	<Record id = "1260602" xlink:href="http://www.aadl.org/cat/rest/record/1260602"/>
	<Record id = "1249532" xlink:href="http://www.aadl.org/cat/rest/record/1249532"/>
	<Record id = "1249531" xlink:href="http://www.aadl.org/cat/rest/record/1249531"/>
	<Record id = "1230466" xlink:href="http://www.aadl.org/cat/rest/record/1230466"/>
	<Record id = "1258774" xlink:href="http://www.aadl.org/cat/rest/record/1258774"/>
	<Record id = "1237981" xlink:href="http://www.aadl.org/cat/rest/record/1237981"/>
	<Record id = "1224899" xlink:href="http://www.aadl.org/cat/rest/record/1224899"/>
	<Record id = "1236034" xlink:href="http://www.aadl.org/cat/rest/record/1236034"/>
	<Record id = "1228878" xlink:href="http://www.aadl.org/cat/rest/record/1228878"/>
</p:Records>

That’s useful to get the hitlist of records for that search. Obviously, those URI’s above denote the corresponding records in REST format. The first one (http://www.aadl.org/cat/rest/record/1249810) looks like:

<?xml version="1.0"?>
<p:Record xmlns:p="http://www.aadl.org"
          xmlns:xlink="http://www.w3.org/1999/xlink">
	<callnum>823 Bu</callnum>
	<author>Burkart, Gina, 1971-</author>
	<fulltitle>A parent's guide to Harry Potter / Gina Burkart</fulltitle>
	<title>A parent's guide to Harry Potter </title>
	<pubinfo>Downers Grove, Ill. : InterVarsity Press, c2005</pubinfo>
	<desc>112 p</desc>
	<bibliography>Includes bibliographical references</bibliography>
	<contents>The Harry hype -- More than a story -- The modern fairy tale -- Discussing fantasy with children -- Morals, not magic -- The real issues in Harry Potter -- Dealing with traumatic experiences -- Facing fears -- Battling bullies -- Delving into diversity -- Hiding hurts -- Letting go of anger -- Getting help -- Choosing good over evil -- The power of love -- Facing spiritual battles</contents>
	<isbn>0830832882</isbn>
	<price>$11.00</price>
	<lang>eng</lang>
	<copies>0</copies>
	<catdate>08-16-2005</catdate>
	<mattype>a</mattype>
	<avail>No copies available</avail>
	<recordlink xlink:href="http://www.aadl.org/cat/seek/record=1249810"/>
</p:Record>

This data would be very easily accessible using something like PHP’s simpleXML. I think one of my next little side projects will be to write a class that accesses this and make it available for download here. Enjoy!