We have started sharing projects created at our Developer House in December, and this week we’re happy to share another. This project and post comes to you from Bill Jones and Steelsen Smith.
The OCLC Developer House was a whirlwind of activity - in just under five days we settled on a project, started work, abandoned our initial approach, started again, and finally came (just shy) of a working prototype in time for the end of week presentations. Packed in alongside software design and development came brilliant (lightning) talks from OCLC staff, edifying conversations with our creative and dedicated developer house peers, valuable meetings with OCLC developers and product managers, great eats from the cafeteria, and an unexpected disruption in OCLC services. Developer House was a breathtaking week, and we’d like to share a little bit about what we’ve started.
What did we build - and why?
We came into Developer House with a background in fulfillment - and plenty of experience with the deceptively simple problem of getting a book from where it’s held to where it’s wanted. Interlibrary loan (ILL) goes back at least to the 8th century, but even with radical advances in automation ILL still depends on degrees of “mind reading” by expert staff. Did this patron really want the 4th edition mailed from Hawaii even though we have the 5th on shelf here? Does the patron know that while the Library of Congress evaluates our request that he or she can be checking out related titles held on site?
Thinking about common slowdowns in fulfillment convinced us that we needed to take on two common scenarios. The first, identifying other versions of the same work that may be available faster. The second, identifying related works that may be useful “while you wait.”
The two scenarios described illustrate the role of “last mile” discovery that’s associated with fulfillment but often forgotten. To help libraries improve the usability of requesting for patrons, our project combines the output of the WorldCat Discovery API and the WorldCat Recommender Service into two panes of a single screen. By conveniently combining these services we’re able to help patrons consume related library resources more quickly and efficiently.
Architecture - what was the plan?
We started by imagining what we wanted - meaningful results for the user. Coming up with this involved brewing together some OCLC APIs and presenting the data in a way useful for fulfillment.
Before we could start work we had to make a few very basic decisions. The first was whether to use PHP for development. Although neither of us had experience with the language, the OCLC Discovery API library is written in PHP and the language has wide acceptance. The second decision we had to make was about what APIs to use. The Recommender Service was a sound choice for getting like-item recommendations, but when it came to alternate editions the various xID tools offered a lightweight alternative to the full Discovery API.
What ultimately swayed us in the direction of using the full Discovery API for alternate editions was its flexibility. By using the same tool, we could get metadata for presentation, availability information for requesting, and detailed information about editions.
With some basic architectural decisions out of the way we were ready to begin writing. Although if you’re curious about how this works in detail your best bet is to review the source code, the overall operation is pretty straightforward. An OCLC number is required to run the search. If one is missing then the search terms are run against the Discovery API to return the first matching OCLC number. That number is then sent to the Recommender Service. It works its magic and the results are parsed for presentation in a “recommendations” box. While that request is running, a request is also made to the Discovery API to get the Work ID for the OCLC number. From this Work ID, we obtain a list of alternative works and present that information in another pane.
In either case the user interacts with a standard HTML page that uses jQuery to make an AJAX call to two different PHP pages, one responsible for alternate editions and the other responsible for recommendations. This ensures that regardless of the presentation layer used the same PHP back end can be used to return the JSON payload with the key work information. We used jQuery UI to create drawers to contain the recommendations and were able to pull together a basic UI pretty quickly.
One of the amazing features of working with the Discovery API is its flexibility. When you pull in the alternate editions, it returns the Work ID, the top level parent, and it tries to figure out from that Work ID what are the children. Sometimes there are a lot from different languages, translations, editions, as well as differences in cataloging. When you work up to the Work ID, you can look at all of those in one place and that allows you to then work backward to find out which OCLC number has the most holdings. That way you don’t wind up with a situation where the patron has submitted a request for the Spanish edition by accident that only has one holding when they really wanted to request something different.
We wrote the project so that it has some handling options for pulling localized fulfillment into your request. For example, when you trigger a recommendation, it allows you to specify what consortia you belong to, so that you can generate a date for when you could expect to receive the item. This can be tied into your historical ILL data to present a more accurate fulfillment date.
So what did we learn and enjoy?
Attending Developer House was an incredibly valuable learning opportunity, and we’re extremely grateful that OCLC was willing to foot the bill for us taking a week away from our normal (all consuming) work lives. And while there was some pretty awesome downtime (learning that Santa feeds fish at the Columbus zoo!) we have to admit, nerdily, that we enjoyed the tech the most.
Working with PHP was one of the most difficult but satisfying parts of the experience. We had to go from 0 to 60 - well, 0 to 5 more like - on PHP in the first day. That was a steep learning curve, but being able to do things in PHP that we can do in other languages, like working with XML or parsing JSON was gratifying.
Learning more about the wealth of information available through OCLC APIs, however, was the technical highlight of the week. The beta and experimental APIs, in particular, were invaluable to our project and show that we can rely on OCLC to provide interesting and useful services that we lack the resources to maintain locally. The Discovery library also made the descriptive data returned by the Discovery API much more intuitive to work with and meant that we could use the API for our purposes without needing to work with RDF and SPARQL.
Finally, we can’t emphasize enough how valuable it was to spend time with library peers and OCLC staff in a semi-structured environment. We were able to learn from each other, find solutions to common problems, and, most importantly, think about discovery and linked data in ways that relate to our jobs that we normally wouldn’t have time to explore. The OCLC Developer House is a fantastic event, and we hope to see OCLC continue offering it.
While mostly functional, our project is still far from finished and also needs to be integrated into some real requesting interfaces. We’re of course open to pull requests and are ourselves working on the following:
- Getting alternate editions to work consistently - right now we seem to get errors using the Discovery library and are trying to work out whether it’s our code or the library
- Having a loading indicator to let people know the app is working
- Adding thumbnail covers
- Linking out to real fulfillment tools
This is quite a list, and we hope to have time to work on these, but we hope the service can be useful before any of this is added into the project.
Check out this application in our Gallery and stay tuned for more projects from Developer House.
The WorldCat Discovery API is currently available as a beta for a select number of libraries using WorldCat Discovery Services. Interested in participating in the beta? Contact us today.