Guest Post by Terry Reese: My A-Z List Ruby Gem and Demo Application

Built on the WorldCat knowledge base API at Developer House

Terry Reese /

If you haven’t been paying attention, OCLC has been quietly working to provide greater developer access to a wide variety of their services.  They’ve been expanding their API offerings, developing tools to simplify exploration of their developer services, and have been revamping their process used to request and manage developer access to their services.  However, more importantly, OCLC has been trying to reach out to the library community in an effort to learn how librarians and developers want to access and use the data OCLC is presently stewarding.  Through hackfests, interactions at conferences, and developer events, OCLC has been working to learn more and actively engage with the library community.

In February 2014, OCLC hosted Developer House, a gathering of library developers to talk about their services and spend some time developing proof of concept projects to test and demonstrate potential project ideas around OCLC’s developer services.  By the end of the week, a number of interesting projects had been developed or started.  As one of the participants of the event, I wanted to highlight the two projects that I completed during that week: an ruby API library for working with the WorldCat knowledge base API and a proof of concept A-Z demo Application that I hope to eventually provide a single click deployment process. 

One of my goals in attending Developer House, is I wanted to set aside some dedicated time to work with some of OCLC’s non-metadata driven APIs.  Because of my work with MarcEdit, I spend a lot of time working with OCLC to find new ways to utilize data found in WorldCat to simplify technical services workflows.  While at Developer House, I wanted to explore a number OCLC’s service offerings and see if the API services that were offered were complete enough to actually utilize for real-world development.

With those goals in mind, I settled on working with OCLC’s WorldCat knowledge base API.  For those not familiar with the WorldCat knowledge base, OCLC offers libraries the ability to upload their journal and database holdings and cooperatively manage the data within WorldCat.  For WorldShare Management Services (WMS) users, this data is used to identify access and generate access links to content.  For WorldCat Discovery users, this information is used to determine what journal and database content a library has access to and drives OCLC’s OpenURL services.  The knowledge base API provides a machine entry-point into this data, providing in theory, all the information necessary for an institution to develop their own custom A-Z list utilizing just the data stored in the knowledge base.  For my part, this is what I set out to do: develop a Ruby on Rails institutional A-Z list application.

In order to develop an A-Z application, I had to develop a new ruby gem to encapsulate support for the WorldCat knowledge base API.  The developed gem, wckbapi, provides a wrapper around the knowledge base API, providing a handful of helper functions developed to simplify interaction with the service.  At this point, the current functions exposed through the gem are:

  • GetEntry
    params -- :id, :entry_uid, :collection_uid
    returns -- Result Object, Entry Object
  • SearchEntries
    params -- :title, :startIndex, :itemsPerPage, :content
    returns -- Result Object, Array[Entry Object]
  • SearchProviders, GetProviderInfo
    params -- :title, :collection_uid
    returns -- Result Object, Array[Providers Object]
  • SearchCollections, GetCollectionInfo
    params -- :title, :institution_id, :collection_uid, :itemsPerPage, :startIndex
    returns -- Result Object, Array[Collection Object]

These helper functions allow a developer to quickly create tools and utilities to quickly query and return information about an institution’s knowledge base information.  For example, returning all the database entries stored in the knowledge base would be accomplished using these two lines of code:

client =

objR, objc = client.SearchCollections(:institution_id, :title => “%”, :itemsPerPage => 25, :startIndex => 1)

The above snippet returns a results object and an array of collection objects that can then be enumerated and outputted to support a specified need.

Once the knowledge base gem was developed, I was able to quickly develop a rough A-Z application demo.  The project code can be downloaded from: and a demo version of the application can be located at:  The proof of concept code was developed to be brief (very little code) and simple to implement for users interested in locally configuring the demo to test it using their own institutional data or for those that simply want to see how the application functions. 

However, in addition to providing a proof of concept, the application highlighted a number of areas within OCLC’s service that could be enhanced, including the core documentation and the need to provide FRBRized results so that journal and database titles can be accessed and utilized in a more straightforward manner.  For their part, OCLC has been responsive in starting to address some of the gaps in their service, and as those gaps are closed, the demo project and source code will be updated to take advantage of the changes.  My hope is that this library and demo code will be useful to the library community and will spur on other development around the WorldCat knowledge base.