Tech Blog

Discovery-Optimized APIs: Requests and Request Options

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

Request Options

To display the relevant request options for a given title there is now a Retrieve Request Options API. This API returns a list of relevant request types along with additional information such as a link. The API accepts a user_id parameter to limit the request options to those relevant to the specified user.

In our Blacklight reference implementation, we call the request options API via AJAX once a patron clicks the physical availability button. When the API returns, we populate the New Request drop down list with the request types returned from the API call.

Note the Retrieve Request Options API is also available on the item level.

The Request Options API returns three types of requests:

Note that the request-options API does not take display logic rules into account.

Request Options View Model

In order to retrieve the relevant request options, we’ve added a route to the Alma WS controller- /bibs/{:mms_id}/request-options. We call the new route asynchronously from the search results when the user clicks on the “physical copy” button.

In the controller, we instantiate a new Request Options View Model passing in the view context. In the view model, we call the Alma Request Options API passing in the logged-in user. Alma returns all of the available request options. General electronic services and broker ILL requests include a request URL and additional information, including the service description. We map those to our return array.

For Alma requests, we must supply a form in our application to support creating such requests. Therefore, before we return the response from the request options API in our controller, we limit the request types to those we support:

request_types = ["HOLD", "DIGITIZATION", "GES", "RS_BROKER"]
request_options["request_option"].select{|o| request_types.include? o["type"]["value"]

Then, for each request option we add a link to our own request form:

obj["link"] =
  .new_request_path(mms_id: params[:mms_id], type: o["type"]["value"])

We return the modified array of request options and use it to populate the request drop down in our application.

Creating an Alma request

To create the request in Alma, we’ve built a new request form in the “patron card” section of our Blacklight implementation. The simple form accepts the MMS_ID of the title and the request type.

In our sample application, we’ve chosen to support hold and digitization requests. We retrieve a list of pickup libraries populated by the Get Libraries API and a list of digitization target departments via the Get Departments API and use those to populate the drop down in the request form.

When the form is submitted, we POST to the Create Request API along with the specified information. When the request is submitted, we redirect to the request list where the new request appears.

Displaying the number of requests

It’s helpful for the user to know how many requests are outstanding for a resource before placing the request. To provide that information, we can use a new expand parameter on the Get BIBs API- expand=requests. This adds a requests node to the BIB object:

  <requests link="">2</requests>

We can then use the information to populate a bubble next to the request options dropdown:

Next Steps

All of the code in this blog post is available in the fulfillment-apis branch of this Github repository.


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.

Have fun!


2 Replies to “Discovery-Optimized APIs: Requests and Request Options”

  1. How would we go about creating an NZ resource sharing request?

    I noticed that the NZ request links include physicalServicesResultId and userId in the URL. However, I am not able to determine how those are generated via the API.

    By Ian Chan on November 17, 2018 at 06:03 AM

Leave a Reply