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