The Aleph API Adapter is a middleware script positioned between the Aleph REST API and any external system that calls the REST API for services. It has a small footprint, is easy to install, and is unobtrusive in operation. Use of the adapter confers these benefits on Aleph customers.
Insulates an external system from a competing vendor’s product and provides an avenue for problem circumvention that does not depend on either Aleph or the vendor.
Can minimize the latency of web traffic. Some queries require several separate operations against the Aleph API. If the external system’s code runs directly against the Aleph API, every one of those queries must make a round trip between the external server and the Aleph server. With the intermediate layer, one call from the external server to the adapter can result in several calls to the Aleph API, all of which are done on the Aleph server using ‘localhost’. None of the ‘localhost’ API calls goes out on the wire and consequently are very fast.
APIs change over time and across releases, contain bugs, and sometimes are incomplete. An intermediate layer can mask changes unless or until they prove useful, and can compensate for missing functionality.
Simplifies access control. Aleph controls access to APIs via IP addresses. Since the X-server is required in order to get Aleph ids for use with the REST API, IP addresses for external servers must be maintained in two places within Aleph: in $alephe_tab/server_ip_allowed and in the Tomcat/JBoss configuration. It is easier to maintain whitelists of approved IP addresses in one place, the adapter, than it is in Aleph. It also gives the adapter more flexibility in serving other processes.
Provides more flexibility for the external system. If there is a need for Aleph data to be filtered, or augmented from other local systems, the adapter is a perfect place to do this without requiring special programming on the external server.
The adapter was built to achieve these design goals.
Easy to integrate into the Aleph server environment.
Have a small footprint and be unobtrusive in its operation.
Return results identical to those generated by the Aleph REST API unless intentionally altered by the customer.
Does not interfere in any way with the standard use of the Aleph REST API through the Tomcat/JBOSS server.
Consumes Aleph REST API URL syntax without modification.
Function in a transparent pass-through mode for all REST API services except for those intentionally modified by the host site.
The adapter is intended to run from the cgi-bin subdirectory on Aleph’s Apache server. During installation, it is activated by the completion of two steps.
Some Apache configuration directives must be activated in Apache to trap REST URLs and route them to the adapter (see the Installation section). If the .htaccess file is in use in the document root of Aleph’s Apache server they can be included there. Otherwise they will need to be included in the main Apache configuration file under a stanza for the document root directory.
The adapter will run on SSL (recommended), port 80, or other ports. For example, some Aleph sites may use port 8991 for their OPAC instead of port 80. The adapter should run on all such configurations without modification.
This URL calls the REST API directly using port 1891:
This URL calls the adapter using SSL:
This URL calls the adapter without SSL using port 80:
This URL calls the adapter without SSL using port 8991:
When the adapter is implemented it does not foreclose the direct use of the REST API on its specified port. The adapter does not interfere with Tomcat/JBOSS operation in any way.
The adapter is written in Perl. Most Aleph servers have two instances of Perl installed: one that is installed with the OS and one that is installed as part of Aleph. The adapter defaults to running under the standard Perl instance installed with the OS. It is not dependent on the Aleph Perl instance. If the adapter is intended to run under the Aleph-specific Perl installation, the first lines of api_adapter.template, install_adapter.pl, and validate.pl must be altered before the installation scripts are run.
The adapter requires that these four packages be present in the Perl instance where it will run.
The adapter uses the server name ‘localhost’ when addressing Aleph’s REST API. Consequently, IP address 127.0.0.1 must be included in Aleph’s JBOSS configuration in /exlibris/aleph/a_/ng/aleph/home/system/thirdparty/openserver/server/default/deploy/jbossweb.sar/server.xml. See Ex Libris manual How to Configure the JBoss Server in Aleph.
Access to the X-server bor-by-key function is required for conversion of aliases into aleph_ids. Column 5 of tab_bor_id. in the ADM library will need to be set to ‘Y’ for each type of identifier that will be submitted from the remote server.
If the adapter is going to be run with id_translation turned off, the X-server whitelist in $alephe_tab/server_ip_allowed must contain IP addresses for all remote servers that will need to look up aleph_ids.
If the ‘RewriteEngine’ and ‘RewriteBase’ directives already exist in .htaccess, they do not need to be repeated.
If the use of htdocs/.htaccess is not enabled on the Aleph system in question, the rewrite rules can either be included at the appropriate place in the Apache configuration, or the use of .htaccess enabled by making a change in Apache’s httpd.conf file. The default version of httpd.conf contains this stanza:
Options FollowSymLinks MultiViews
Allow from all
Change ‘AllowOverride None’ to ‘AllowOverride All’. Apache should be restarted after making this change.
Run the installation script with this command:
The installation script will perform the following operations:
Get the PWD environment variable and extract the version token from the path.
Prompt the installer for the institution’s name. This will be used in the adapter’s response to an ‘ilsinstance’ call, the one non-Aleph call that it accepts. Here is an example of the structure returned by the ‘ilsinstance’ call, reporting the institution’s name, the version of Aleph, and a few site-specific Aleph variables:
MIT 22.0.3 en_US Eastern Standard Time EST USD
Prompt the installer for the Tomcat/JBOSS port number.
Prompt the installer for an Aleph patron id to be used in verifying the installation.
Prompt the installer for the IP address of each remote server that will call the adapter.
Generate the ‘api_adapter.cgi’ script from a template, interpolating the server IP addresses into the whitelist and the JBOSS port number into the appropriate variable.
Run validate.pl to test the installation. Validate.pl will perform the following operations:
Verify the presence of the required Perl packages and report success or failure.
Using the Aleph id supplied by the installer, construct and submit a URL to the X-server and report success or failure.
Using the Aleph id supplied by the installer, construct and submit a URL to the REST API and report success or failure.
Verify the operation of the get_aleph_info.csh shell script.
If no errors are reported by the installation and validation scripts, the installation is complete. The validation script generates and displays a test URL. Test this URL from any server whose IP address was specified during installation. It can be tested from a browser if the browser’s IP address is part of the server whitelist.
The adapter has one optional control, id_translation. This option is useful when the external system submits REST URLs that contain an alternate identifier instead of an Aleph id. With id_translation set on (the default), the adapter extracts the incoming alternate identifier from the URL, calls the X-server to get the corresponding Aleph id, and substitutes the Aleph id for the alternate identifier in the call to the REST API. If this conversion of identifiers is not needed, id_translation can be turned off. If a remote server needs to call the REST API with an alternate identifier, one of three scenarios must be followed.
The adapter is not installed.
In this case, the remote server must first call the X-server’s ‘bor-by-key’ function, passing the alternate identifier and receiving the corresponding Aleph id. The Aleph id can then be interpolated into subsequent calls to the REST API.
The adapter is installed, but id_translation is turned off.
This case requires the same process as case #1.
The adapter is installed and id_translation is turned on (default)
In this case the remote server calls the adapter with a REST URL containing an alternate identifier. The adapter extracts the alternate identifier, calls the X-server to retrieve the corresponding Aleph id, replaces the alternate identifier in the URL with the Aleph id, and sends the enhanced URL on to the REST API. Since the X-server call in this case is done on the local server without going out on the network it is very fast
Under what circumstances should id_translation be turned off?
If the remote server is populating all its REST URLs with Aleph ids, then the translation step is wasted processing time. In that case, id_translation can be turned off with these actions:
Make a backup copy of api_adapter.cgi.
Find this text ‘my $id_translation = 1;’ and change the 1 to a zero.