RESTful Web Services

Purpose

Information about the resources available to library users is commonly maintained in an Integrated Library System (ILS) that manages acquisitions, cataloging, circulation, and reporting. The integrated functions of the ILS help streamline library operations, and the data the ILS manages provides valuable information about a library’s collections.

In recent years, discovery tools such as the Ex Libris Primo® discovery tool have become popular, enabling patrons to see resources available outside the scope of traditional ILS holdings, including journal articles, resources available at nearby institutions, and interactive forums. At the same time, the bibliographic data and services that the ILS manages are crucial for the effective use of libraries. These trends imply that the ILS needs to become a platform that supports appropriate interfaces for discovery applications residing on top of it. The Voyager RESTful API creates a hierarchy of resources that are exportable and enables client discovery tools to build a suite of interfaces for the library’s patrons on top of the Voyager API. This enables the implementation of a single interface that efficiently handles both the discovery and the fulfillment actions.

The RESTful APIs provide access to Voyager services in a hierarchical format and enables client discovery tools to build a suite of interfaces for the library’s patrons on top of the Voyager API. This enables the implementation of a single interface that efficiently handles both the discovery and fulfillment actions.

The APIs can be divided into two categories:
1. Patron/Account related
2. Bib/Holdings/Item related

Patron Services

The main function of Patron APIs is to provide information about the patron’s circulation status and activity. In Voyager, this information is found on the My Account tab in WebVoyáge.

The APIs can be accessed in a hierarchical manner. To see all possible information about a patron, use the basic Patron service. The XML returns links to all of the lower-level patron information. The following is a breakdown of the hierarchy:

Patron

PatronPatron information (includes patron address)

Patron > Circulation Actions

Patron > Circulation Actions > Loans

Patron > Circulation Actions > Debt (Includes fines and Demerits)

Patron > Circulation Actions > Requests (includes Holds, Recalls, Callslips, Shortloans, Remote Storage, Media Booking, and UB Requests)

Patron > Patron Status (Registration) > Blocks (includes messages)

Bib-related Services

Information can be determined about a bibliographic record plus holdings and item records, too. In addition, if a patron ID is included, information about the patron’s privileges related to that bib/item are returned.

Record

Record > Holdings (can ask for this with view=items to get holdings with associated items)

Record > Items (in order to see items only, no holdings records)

And, when a patron is introduced, the types of requests that the patron can perform are included.

Record (with patron)

Record (with patron) > Hold requests per title

Record (with patron) > Recall requests per title

Record (with patron) > Callslip requests per title

Record (with patron) > Other requests per title (this includes requests not listed above, like ShortLoan, Media Booking, Bib Requests, ILL, and locally created requests)

Record > Items (with patron)

Record > Items (with patron) > Hold requests per item

Record > Items (with patron) > Recall requests per item

Record > Items (with patron) > Callslip requests per item

Record > Items (with patron) > UB requests per item

Other Services

Authorized patrons may make ILL blank requests.

illblank

Alphabetical List of Services

NameSummary
Basic ItemThis resource may be accessed with a GET method to retrieve items information for a specific item record.
Call Slip Per ItemThe resource may be accessed with a GET method to retrieve a specific patron’s call slip request information for a specific item. The resource may be accessed with a PUT method to create a call slip request for a specific patron and on a specific item.
Call Slip Per TitleThe resource may be accessed with a GET method to retrieve a specific patron’s call slip request information for a given title. The resource may be accessed with a PUT method to create a call slip request for a specific patron and on a specific title.
Hold Per ItemThe resource may be accessed with a GET method to retrieve a specific patron’s hold request information for a specific item. The resource may be accessed with a PUT method to create a hold request for a specific patron and on a specific item.
Hold Per TitleThe resource may be accessed with a GET method to retrieve a specific patron’s hold request information for a given title. The resource may be accessed with a PUT method to create a hold request for a specific patron and on a specific title.
ILL Blank RequestA list of available system-defined ILL blank requests for the patron’s home server may be accessed with the GET method. An ILL blank request may be submitted to the patron’s home server using the PUT method.
MARC Field OrderThe resource may be accessed with a GET request to retrieve a list of available MARC field order configurations. The resource may be accessed with a POST request to sort a MARC record based upon the supplied MARC field order configuration.
PatronThis resource may be accessed with the GET method to retrieve new patron self-registration parameters on patron home server. A new patron can self register with the PUT method after entering all required parameters. The definition of parameters can be defined in SysAdmin –> Web Services –> Patron Self-Registration. Last name and address line 1 are the required parameters.
Patron AddressThe resource may be accessed with a GET method to retrieve a specific patron’s information. The patron’s address cannot be updated by the end user in Voyager. Starting version 9.0.0, depending on SysAdmin -> WebServices -> Service Configuration, a user can allow to edit SMS number, or patron pin.
Patron Blocks
Patron Circulation ActionsThis resource may be accessed with the GET method to retrieve patron circulation actions such as loans or requests from the patron home server.
Patron Circulation Actions — DebtThe resource may be accessed with the GET method to retrieve a patron’s fines and fees and/or demerits (debt) from a patron’s home server.
Patron Circulation Actions — LoansThe resource may be accessed with a GET command to retrieve the patron charged item information from the patron home server. The resource may be accessed with a POST command to renew a patron charged item.
Patron Circulation Actions — RequestsThe resource may be accessed with the GET method to retrieve a patron’s requests from the patron home server. The resource may be accessed with the DELETE method to cancel a patron’s request.
Patron RegistrationThe resource may be accessed with a GET method to retrieve a specific patron’s registration.
Patron Requests Per TitleThe title level request resource may be accessed with a GET method to retrieve a link to services that are not available via the VXWS. This returns a list of possible links. The patron is prompted to enter his/her logon information with the Voyager front end. The patron is then presented with the desired page. This service only sends requests of types that have not already been provided by VXWS. That is, this service does not send information about requests of type Hold, Recall, Call Slip, or UB Request. The link is supplied in the results as a fully formulated, functioning link. The vwebv:port should be a customer-defined base URL configurable in the VXWS configuration file. If this is not supplied or is blank, the URI is not constructed. The skin is a locally customized view of the Voyager OPAC. Voyager customers may want to choose a specific skin for the OPAC that is used for this purpose and is configured in the VXWS configuration file in Voyager. If this is not supplied or is blank, the parameter can be left off of the URI.
Recall Per ItemThe resource may be accessed with a GET method to retrieve a specific patron’s recall request information for a specific item. The resource may be accessed with a PUT method to create a recall request for a specific patron and on a specific item.
Recall Per TitleThe resource may be accessed with a GET method to retrieve a specific patron’s recall request information for a given title. The resource may be accessed with a PUT method to create a recall request for a specific patron and on a specific title.
RecordThis resource may be accessed with a GET method to retrieve a specific record from the server home of the record. The output may indicate if there are holdings or items under the record. Optionally, if a patron is specified, it also displays whether certain requests such as a hold or call slip can be requested by the patron.
Record HoldingsThis resource may be accessed with a GET method to retrieve holdings for a specific bibliographic record from the record home server.
Record ItemsThis resource may be accessed with a GET method to retrieve items information for a specific bibliographic record. Optionally, if a patron is specified, it also displays whether certain requests such as a hold or call slip can be requested by the patron.
UB Request Per ItemThe Universal Borrowing Request resource is used to determine what can be requested and where it can be picked up. The resource is accessed with a POST method to retrieve a specific patron’s UB request information with an accompanying XML form with a list of record IDs and associated database codes. The Universal Borrowing Request Item resource may be accessed with a PUT method to create a UB request for a specific patron and on a specific item.