Discovery-Optimized APIs: Physical Holdings and Online Resources
Alma works great with the Ex Libris discovery systems – Primo and Summon. But we also recognize that some institutions want to develop their own discovery systems. This approach may come from a desire to have a completely tailored discovery experience, or as a response to the need to expose collections and content other than that cataloged in the library system.
In the past, we’ve developed a reference implementation using the Blacklight open source discovery platform. We’ve previously blogged about the implementation in the following posts:
This work has been well-received and institutions are happy to know they have a choice in discovery options. The reference application implements fulfillment functionality (locations, items, requests, etc.) by leveraging a mash-up provided by Alma. This approach allows complete customization of the discovery experience while “outsourcing” the complex fulfillment logic to the Alma.
Looking at a continuum of flexibility in discovery customization, we’ve satisfied the needs of most institutions with the work done so far. Primo provides UI customization while the open-source route allows for a more tailored experience. There is a small number of institutions that are interested in complete flexibility in their open source discovery system and who want to develop even the fulfillment options on their own. 
To meet those needs, we’ve been investing in discovery-optimized APIs. While developing fulfillment functionality is not a trivial undertaking, these APIs enable more efficient access to the data required. In this blog post, we’ll look at a few of the APIs added in recent versions of Alma. In the coming months, we’ll explore additional discovery-optimized APIs as they are released.
Holdings List & Availability
The Retrieve BIBs and Retrieve BIB APIs support an expand parameter which retrieves print, electronic, and digital availability:
/almaws/v1/bibs/{mms_id}?expand=p_avail,e_avail,d_availThe API returns availability-related information in pseudo-MARC fields. For our purposes, we’re interested in the fields required to display a location list, the call number, and the number of copies available. According to the documentation, this information is available in the following subfields of the AVA fields:
- $$c – Location display name
- $$q – Library name
- $$d – Call number
- $$f – Total items
- $$g – Non-available items
To implement the list, we’ve returned to the Blacklight/Alma reference application described in the previous blog post, and modified it to remove the fulfillment options mashup. We want to replace the mashup with a series of REST API calls which will be used to display availability information in the UI. We’ve added an Alma Web Services controller to our project (almaws_controller.rb) along with routes for the necessary API calls.
We expose a method called /almaws/bibs/availability which accepts a list of MMS IDs from the result list returned by Blacklight. In the controller, we create a new instance of an AvailabilityViewModel class and pass in the view context. In the view model, we still call the Alma Get BIBs API to retrieve real-time availability, but we massage the response from the API to include everything needed by the client to display the availability information. On the client side, we’re using the DataTables jQuery plugin to supply the HTML for our location list. So in our view model, we create two nested arrays representing the columns and rows in the table- one for print locations and one for online resources. In the JavaScript file accompanying the catalog view, we build the rows from the data returned in the web service call.
The end result is a table showing the locations where the book is available along with additional helpful information:
Item List & Fulfillment Policy
In our location table, we’ve added a “Details” button on each line. Since there can be many items (especially for a serial), we want to retrieve the data asynchronously and configure the DataTable to call our service via AJAX whenever additional data is needed. To accomplish this, we’ve implemented the pattern suggested by this useful post. This involves the creation of a new endpoint in the AlmawsController and the creation of a new ItemsViewModel. The view model retrieves the items for the specified location by calling the Alma Retrieve Item List API. In order to show the due date policy, we add an expand parameter to the call. We also pass in the user logged into Blacklight so that Alma can calculate the correct policy.
/almaws/v1/bibs/{mms_id}/holdings/{holding_id}/items?expand=due_date_policy&user_id={user_id}
When DataTables needs additional information, or when the user requests the table be sorted or filtered, our service endpoint is called by DataTables with the appropriate parameters. The parameters are used to construct the call to the Retrieve Items API. The end result is a display of the item’s barcode and the calculated due data policy.
Temporary Locations
An item can be associated in Alma with a temporary location. In such a case, it is no longer considered part of its permanent holding record and cannot be retrieved using the Retrieve Item List API with a holding ID. To handle this scenario, the Retrieve Item List API in Alma now supports an “ALL” keyword which will search for items in any holding record. We add querystring parameters for the current library and current locations as follows:
/bibs/{mms_id}/holdings/{holding_id}/items?current_library=MAIN¤t_location=reference
Online Resources
To show online resources, both electronic and digital, we utilize the other real-time availability pseudo-MARC fields returned in the Retrieve BIB API. Using the information contained in those fields, we can build a display which includes information relevant to patrons. For electronic portfolios, for example, we can use the following subfields from AVE:
- $$m – Collection name
- $$s – coverage statement
- A link based on $$u (with the rft.mms_id parameter replaced by the portfolio_pid parameter along with Force_direct=true to redirect to the resource)
For digital resources, we use the following subfields from AVD:
- $$e – Label
- A delivery link based on the representation ID stored in $$b
The result is a table listing the various online options for the specified title and a direct link to view the material.
Next Steps
All of the code in this blog post is available in the fulfillment-apis branch of this Github repository. In addition, a demo site is available online as of when this blog post was published.
To get involved in the discussion, you can join the Ex Libris Alma & Open Source Discovery Google Group. There you can ask questions, give feedback, or make suggestions.
And finally, keep an eye on this space for more blog posts in the coming months.