 |
 |
On May 8, 2008, at 11:25 AM, Dr R. Sanderson wrote: >> However, if there was no API available, only a SRU service, wouldn't >> you complain about something else that SRU didn't do? > > Like what? The current API seems to be concerned with search. Search > is what SRU does well. If it was concerned with harvest, I (and I'm > sure many others) would have instead suggested OAI-PMH. BTW, at an OpenLibrary meeting that took place a couple of months ago I mentioned and advocated for the use of both SRU and OAI-PMH. From my travel log: The afternoon was given up to a number of break-out sessions to discuss specific issues. I participated in the discussion surrounding APIs to integrate Wikipedia with Open Library. The desire is to allow people to cite books in Wikipedia by: 1) searching for title or key, 2) returning a list of results, 3) selecting an item, 4) having the system create a citation for the item, and 5) inserting the citation into a Wikipedia article. Then, on a regular basis, these citations will be checked and updated ensuring their integrity. Everybody in the group supported the concept of REST-ful Web Service computing to accomplish the task, but not everybody's definition of REST-ful computing was congruent, and a bit of a religious war ensued. I tried to advocate for the use of SRU as the search protocol, but ultimately people leaned towards OpenSearch. "SRU is too complicated." Regarding the citation checking the discussion surrounded the requesting of one or more identifiers from Open Library and returning a stream of metadata. Here I tried to advocate for another existing, well-established standard -- OAI-PMH -- but again I was shot down. "Too complicated." In reality I think two things worked against the adoption of SRU and OAI. First my description of their functionality was not as eloquent as it could have been, and second, the Open Library personnel had never heard of nor knew anything about either protocol. This is another example of library standards being too library-centric. Think Z39.50. [1] After (re-)reading the OpenLibrary API [2], I don't think it really supports search, and at this time I don't think something like SRU or OpenSearch could be implemented on top of it, unless the queries were very specific, such as control number searches. And while I wish OpenLibrary would support SRU and/or OAI-PMH, I am really glad there is at least an API. It is REST-ful. Nice. Returning JSON is okay. XML would be nice too. In short, I think the API is a step in the right direction. Here are a number of more specific observations: * In a sentence, define what Open Library is and what its goals are. Given such a definition and scope statement developers will have an idea whether or not they are stealing information or not. I think they won't be, but I do think it is important to be explicit. Remove any doubt. * Define Infogami. "Open Library is driven by an underlying system/ database we call 'Infogami', and this documentation describes a REST- like API for reading content from it." * List and/or enumerate a number of ways the API can be used. "Given an ISBN number, Infomami can return a link to an item in any one of a number of formats as well as additional metadata such as author names, titles, abstracts, reviews, and cover art. Other functionality includes..." * Distinguish to a greater degree the stylistic differences between links and code in the documentation. There were many times when I thought styled text (such as get, query, type/template) were hotlinks. * Enumerate the different types of objects that can be retrieved from the system and maybe organize them into logical groups. Do the same thing for the types. I think I found this to be the most confusing aspect of the documentation. * For each type, provide a normative example complete with output. Ideally, each type would be additionally elaborated upon with a typical use case. "Use the /type/author/title to retrieve the title of an author. Here's a sample query, and here is the output..." * Regarding the curl examples, enclose the URLs in double quote marks since many shells will interpret the ampersands incorrectly. * Finish off the documentation with one or more example applications that a developer can cut & paste into their editor. One application might be client-based -- Javascript in an HTML head element. Another might be server-based. [1] http://www.library.nd.edu/daiad/morgan/travel/open-library/ [2] http://openlibrary.org/dev/docs/api -- Eric Lease Morgan Hesburgh Libraries, University of Notre Dame