Introduction to Aleph RESTful APIS

General Purpose

The Aleph 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 Aleph API. This enables the implementation of a single interface that efficiently handles both the discovery and the fulfillment actions.
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 living on top of it. The Aleph 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 Aleph API. This enables the implementation of a single interface that efficiently handles both the discovery and the fulfillment actions.

The Aleph RESTful API is based on the technical recommendations of Digital Library Federation’s ILS Discovery Interface Task Group (ILS-DI).

Product Version Compatibility

Versions 18, 20.1 and later

Interface Type

General Material

The Aleph API and REST

The following diagram illustrates how the API is used:

a diagram that illustrates how the API is used

Representational state transfer (REST), which is a style of software architecture for distributed hypermedia systems, has been used to implement the API. Being a scaleable and easy to use architecture, the Aleph RESTful API implements the following concepts:

    1. Application state and functionality are abstracted into hierarchical resources;
    2. Every resource is uniquely addressable using Uniform Resource Identifiers (URI);
    3. All resources share a uniform interface for the transfer of state between client and resource, consisting of:
      • A constrained set of well-defined operations (HTTP methods GET, POST, PUT, and DELETE)
      • XML structured replies

The following hierarchy tree illustrates the Aleph API resources tree:

The following hierarchy tree illustrates the Aleph API resources tree

The resources tree may be viewed as supporting the following functions:

  • Get Patron Information – The Get Patron Information function returns specified information about the patron, based on options in the request. This function can optionally return the patron’s contact information, fine information, hold request information, loan information, and messages.The function utilizes the following resources tree using the GET and POST (for Address / Password) HTTP method:

Get Patron Information

  • Renew Loan – The Renew Loan function renews a patron’s loan, list of loans, or an ILL request.The function utilizes the following resources tree using the POST HTTP method:

Renew Loan

  • Cancel Hold – The Cancel Hold function is used to cancel a patron’s hold requests, booking requests (including short loan requests), ILL requests, photocopy requests, and acquisition requests.

The function utilizes the following resources tree using the DELETE HTTP method:

Cancel Hold

  • Get Patron Status – The Get Patron Status function returns a message with the patron’s borrower type, status, and expiration information.
    The function utilizes the following resources tree using the GET HTTP method:

Get Patron Status

  • Get Services – The Get Services function returns an enumerated list of services available for a particular patron on a specific title or item.
    The function utilizes the following resources tree using the GET HTTP method:

The Get Services function

  • Request Title – The Request Title function creates, for a patron, a title-level hold, short loan, or ILL request on a given bibliographic record in the ILS.
    The function utilizes the following resources tree using the PUT HTTP method:

Request Title

  • Request Item – The Request Item function creates, for a patron, an item-level hold or short loan request on a specific item of a bibliographic record in the ILS.
    The function utilizes the following resources tree using the PUT HTTP method:

Request Title

  • Get Records – The Get Records function returns items and holdings information for a given bibliographic record.
    The function utilizes the following resources tree using the GET HTTP method:
    Get Records

API Guidelines

The following guidelines are used for querying the resources tree:

  • The base URI is made up of <server address>:<jboss port>/rest-dlf/
    For example: http://server.name:1892/rest-dlf/
    Please note the “/” (ending slash).
  • Every sub-resource may be accessed after a specific instance of the father resource is specified. For example:
    <base URI>/patron/<patron id>/record/<record id>/holds
  • Requesting a resource without specifying a specific instance will normally result in a list. For example:
    record/<record id>/items – will retrieve an items list.
    record/<record id>/items/<item id> – will retrieve a specific item.
  • Many of the URIs may be used with an optional parameter. For example:
    record/<record id>/items?view=fullRefer to the resources’ documentation pages for a description of each resource’s usage and parameters.
  • All replies are in XML format. Refer to the resources’ documentation pages for a description of each resource’s XML representation.
  • All XML replies include a reply-code element and a reply-text element that reports the status of the requested query or action.
  • A language parameter may be used with each URI, in the format lang=<language code>.
    For example, /patron/<patron id>/record/<record id>?lang=eng.
    It is therefore recommended to use ISO 639-3 (ISO 639-3:2007) when setting up languages in the system.

Configuring the API

API-specific text messages are located in the aleph/error_<lng> directory. The file names align with the services described above:

aleph/error_<lng>:

  • dlf_renewloan
  • dlf_getpatroninfo
  • dlf_cancelhold
  • dlf_getpatronstatus
  • dlf_getrecords
  • dlf_requestitem
  • dlf_getservices
  • dlf_requesttitle
  • dlf_global

if localization is needed, copy these files from the aleph/error_eng directory to your local alephe/error_<lng> directory, and translate them.

Similar to X-Services, the API response may be altered using trn and tag files:

trn files convert raw data exported by the DLF services to a textual description. For example, item collection is displayed as “General” instead of the code “GEN”.

The files are located in the aleph/dlf_<lng> directory , and they align with the functions described above:

aleph/dlf_<lng>:

  • dlf-renewloan.tag\dlf-renewloan.trn
  • dlf-getpatroninfo.tag\dlf-getpatroninfo.trn
  • dlf-cancelhold.tag\dlf-cancelhold.trn
  • dlf-getpatronstatus.tag\dlf-getpatronstatus.trn
  • dlf-getrecords.tag\dlf-getrecords.trn
  • dlf-requestitem.tag\dlf-requestitem.trn
  • dlf-getservices.tag\dlf-getservices.trn
  • dlf-requesttitle.tag\dlf-requesttitle.trn
  • dlf-global.tag\dlf-global.trn

if localization is needed, copy these files from the aleph/dlf_eng directory to your local alephe/dlf_<lng> directory, and translate them.
Note that when manipulating the API export, the effect on the client systems must be considered.

Possible Error Codes

CodeText
0ok
1The supplied institution ID is not valid
2The patron ID is invalid
3Loan does not belong to the requested patron
4Cash charge does not belong to the requested patron
5Request does not belong to the requested patron
6Loan does not exist
7Cash charge does not exist
8Request does not exist
9Patron is not permitted to update address information
10Wrong password. Enter password again
13Request cancellation failed
19Record does not exist
21Group does not exist
23Missing mandatory field(s) in address
25Failed to create request
26Holding does not exist
27Item does not exist
28Renew Failed
29Invalid input xml
100General ILS failure
101Requested API version is not supported

Note: The texts are configurable and language-sensitive.

Web Services server Configuration (JBoss / Tomcat)

The API is activated through the WEB Services Server (until Aleph 21 it is JBoss server, in Aleph 22 it is Tomcat). Util w/3/7/9 may be used to run the JBoss / Web Services server. Util w/2/7/1 may be used to stop the JBoss / Web Services server.

The JBoss / Web Services server may be started automatically by adding the following to alephe/aleph_startup:

#*******************************************
#       J BOSS
#*******************************************

cd $aleph_dev/ng/aleph/home/system/bin

bash jboss_startup.sh

echo " "
echo "All done "

The ./alephe/jboss_conf/main.properties file includes required configurations for the JBoss / WEB Services server (Tomcat). This file is automatically created during installation.

In order to configure it after upgrading from old Aleph version, perform the following steps:

  1. Stop JBoss / WEB Services server by using util/w/2/7/1 .
  2. Configure $aleph_dev/ng/aleph/home/profile/global.properties file with the customer’s port, and update $alephe_root/jboss_conf/global.properties as well.
  3. Run: $aleph_dev/ng/aleph/home/system/bin/set_globals.sh .
  4. Start JBoss / WEB Services server by using util/w/3/7/9 .