Ready to Learn?Ex Libris products all provide open APIs

Tech Blog

 

Discovery-Optimized APIs: Working with Serials

Josh Weisman on March 20th, 2018

In a previous blog post, we explained the background and rationale behind offering discovery-optimized APIs. In a recent Alma release, additional support has been added for the display of serials. In this post we review the new features and how those features were utilized in our Blacklight reference application.

Location list for serials

To provide an appropriate display for serials, we first need to determine if the specified title is a serial or monograph. After calling the Retrieve BIBs API to receive real-time availability information, we look through the returned AVA fields to search for a $$t (summary holdings information from 866) or $$h (calculated summary holdings when no 866 field exists). If either one of those two subfields is present, we assume the title is a serial.

Note: An alternative approach is to look for any items with a description. To accomplish that search using APIs, you can use the new filter fields along with the "ALL" holdings alias to search in all items in all holdings:

/almaws/v1/bibs/{mms_id}/holdings/ALL/items?q=description~*&limit=0

Once identified as a serial, we display the summary holdings information from subfields t or h. We also don't show request information at the title level since we'll want to enable item-level requesting for serials. We'll provide more information on using the APIs to enable requests in a future blog post.

The result is a location list optimized for serials:

Discovery APIs - Serials

Item list for serials

We want to make a few changes to the item list for serials as well. First, we'll display the item description rather than the barcode. We'll offer a request button at the item level. And we display a search box to allow the user to search for the desired issue or item.

Since there may be quite a few items, we want to use the AJAX capabilities of the DataTables plugin to enable search on the server side. We've implemented the pattern demonstrated in this excellent post to support this functionality in our application. We created an ItemsViewModel which provides the data in the format required by DataTables.

The Alma Retrieve Items API now supports filters for the following fields: enum_a, enum_b, chron_i, chron_j, description. Ordering of the results is enabled for the following fields: chron_i, description, enum_a, enum_b, enum_c, library, location or temporary_location. Our view model uses these parameters to fetch the relevant data as follows:

/almaws/v1/bibs/{mms_id}/holdings/{ID}/items?limit=5&offset=0&expand=due_date_policy&user_id={user_id}&q=description~[search]&order_by={sort_column}&direction={sort_direction}

Together these additions to the APIs enable an efficient display for serial titles.

Discovery APIs - Serials Items with Search

 

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.

Github

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.