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 > Patron information (includes patron address)
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 > 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) > 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.
Alphabetical List of Services
| Name | Summary |
|---|---|
| Basic Item | This resource may be accessed with a GET method to retrieve items information for a specific item record. |
| Call Slip Per Item | The 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 Title | The 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 Item | The 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 Title | The 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 Request | A 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 Order | The 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. |
| Patron | This 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 Address | The 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 Actions | This 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 — Debt | The 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 — Loans | The 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 — Requests | The 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 Registration | The resource may be accessed with a GET method to retrieve a specific patron’s registration. |
| Patron Requests Per Title | The 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 Item | The 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 Title | The 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. |
| Record | This 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 Holdings | This resource may be accessed with a GET method to retrieve holdings for a specific bibliographic record from the record home server. |
| Record Items | This 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 Item | The 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. |