Ready to Learn?Ex Libris products all provide open APIs

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:

rest-dlf-schema-aleph22_01-intro-http-aleph-api

 

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:

Slide1-all

 

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: 

 

Slide10-patron_get-post     

  • 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:

Slide3-patron-patron_id_circ_actions

        

  • 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:

Slide4-patron-patron_id-circ_actions-requests

        

  • 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: 

Slide5-patron-patron_id-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:  

Slide6-patron-patron_id-records-all

        

  • 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:    

Slide7-patron-patron_id-records
        

  • 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:    

Slide8-patron-patron_id-records-items

        

  • 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 PUT GET method: 

Slide9-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=full

         Refer 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

Code     Text

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

Note: The texts are configurable and language-sensitive.

JBoss Configuration

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. 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 .