Ready to Learn?Ex Libris products all provide open APIs

Getting Started with Alma APIs

Alma RESTful APIs provide access to data and workflows stored in Alma. The Developer Network is your key to getting the most out of these APIs. Here you’ll find documentation for each of the interfaces, including a full description of the parameters and the data objects. You can view all of the documentation without logging in to the Developer Network. However, to try out the APIs or to use them to access your data, you’ll need a Developer Network account.
 
 

Logging In

If you are a developer at an Alma institution, an account has already been created for your institution. Contact your institution’s technical contact person in order to get an invitation to join the institution group. Once you have joined your institution’s group, you will be able to create and edit your institution’s applications.
 
If you’re not yet an Alma customer and would like to try out our APIs, you can create an account and use the APIs against our Guest Sandbox.
 
The Guest Sandbox is our demo environment. Users who do not have an institutional account can run our APIs and apply the GET method to retrieve results from our demo environment. However, guests cannot apply the POST and PUT methods.
 
To sign up as a guest user of the Developer Network:
 
  1. On the API portal home page, in the upper right corner, click Signup:

 

The registration form appears:

 

  1. Fill in the required personal information, click I accept the above, and click Register Now.
    An email message with an activation link is automatically sent to you.

  1. In the email message that you received, click the link to activate your account.
 
Congratulations! You now have a Developer Network account and can use our APIs, write a question in a forum, and add blog posts.
 

Using Alma APIs

To learn about the structure of APIs and how they should be used, see the article "How we're building APIs at Ex Libris".

 

Defining an application

To use an Alma API with an external application, you have to define the application in the API portal and receive an API key:
  1. In the left pane, select ”Applications”: 

  1. On the right, click Add Application.
    An application wizard with tabs appears:

  1. On the Application Information tab, add the relevant application information. The information for Application Name and Platform is required.

 

  1. On the API Management tab, list the APIs that are used by the application:

      a. From the API list, select an API.

     b. Read the terms of use and accept them.

          The selected API appears under Current APIs       .

     c. To add more APIs, repeat the process.

     d. Click Save.

  1. Your application is defined and is assigned an API key:

An API key is necessary for authenticating API requests. You must include it as a parameter in the URL when calling an Alma API—for example, apikey=iyr4h238r4. See Calling Alma APIs.

 

Selecting an API plan:

Environment access is controlled by API “plans”. In addition to the Guest Sandbox, four API plans are available: read/write and read-only plans for your production environment and read/write and read-only plans for your sandbox environment. It is recommended that you use an API against a sandbox environment first. Later on, you can update the API to work against a production environment.

  1. Point the API key to your own environments by clicking the gear icon, and select Edit:
  2. Under Plan Change, select an API Plan:

Calling Alma APIs

Alma APIs are implemented in the REST style. This means that you can call Alma APIs from a variety of development environments, and even from your browser.  .

In your external application, a call to an Alma API should be directed to the geographic location of your library, as follows:

America: https://api-na.hosted.exlibrisgroup.com
Europe: https://api-eu.hosted.exlibrisgroup.com
Asia Pacific: https://api-ap.hosted.exlibrisgroup.com
Canada: https://api-ca.hosted.exlibrisgroup.com
China: https://api-cn.hosted.exlibrisgroup.com

 

When you call an Alma API, you must include the API key as a parameter in the URL, as in apikey=iyr4h238r4. The API key is required for authenticating the call and directing the request to the relevant institution and the environment in the API plan that you selected (sandbox or production).

If you want to send the API key as a header instead of in the URL, use the following syntax:

Authorization: apikey {APIKEY}

To try out your newly created API key, make a simple call in a browser. Direct the call to your region (as shown earlier), and add the following string to the end of the URL: /almaws/v1/users?apikey=XXXXX. You should receive a list of the users defined in either the Guest Sandbox or your institution, depending on the configuration of the API key.

The Developer Network also includes an API explorer, which you can use to test out additional Alma APIs. To access the API explorer, go to https://developers.exlibrisgroup.com/alma/api-explorer.

 

Using the API Console

The Developer Network’s API console enables you to test out the Alma APIs. The API console is available here and also on each API documentation page, where you can click the Try It Now button.
 
To use an API through the API console:
Note: If you have reached the API console from the Try It Now button, the API is already selected, so skip to step 2.
  1. Select an API, a resource (the API’s URL), and a method:

The API request form appears. It includes the parameters relevant to the specific API, and default values:
  1. Review the form, and enter the parameter values that are relevant to the API data that you want to submit.

The Select an Application list displays the relevant applications for the selected API:

  1. From the Select an Application list, select the application that you want to use, and click Authentication.

 

  1. In the list that appears, select API Key

The API key of the selected application appears.

  1. Click OK

  1. Submit the API request by clicking Execute Request.

The response is displayed on the Response tab.

Note:

  • On the Query tab, you can see the entire query in a format that you can use for further testing. In addition, you can select a programming language and obtain a code sample with that specific API call.
  • The API console currently does not support POST requests that include query parameters. You can use an external REST client to try such APIs. Remember to always include a content-type header for a POST or PUT method (with application/xml or application/json), even when no payload is sent.

 

Migrating existing applications to the API Platform
 
If you have an existing application built with Alma APIs, you can migrate them to the new platform to gain the benefits of working with the latest standards and tools.
 
To migrate applications using REST APIs:
  • Log in with institution credentials.
  • Create application in the Portal, indicating the relevant APIs.
  • Change your external application to use key and point to new URL.
  • HTTP Basic authentication is no longer needed 

Structure of the REST URIs

The Alma RESTful API provides access to resources (data entities) via URI paths. To use a REST API, your application will make an HTTP request and parse the response. 

The standard HTTP methods: GET, PUT, POST and DELETE will be used in order to perform actions on the URI resource: 

  • GET - retrieve a resource
  • POST - create a resource
  • PUT - update a resource (in a "swap all" mode)
  • DELETE - delete a resource

URIs for Alma RESTful API resource have the following structure: 

https://gateway-hostname/almaws/version/resource-name/parameters?additional_parameter=value&apikey=your_key 

Versioning

Currently all of the Alma RESTful API are in v1. Our APIs are backwards-compatible and so if we add optional parameter to the URL or tags and attributes to the returned data - we consider it still as version1. If we'll need to remove or rename tags, or change the behavior of an existing URL (or any other non-backwards-compatible change), we will create a new version for that API, announce it, and gradually deprecate the old version.
 

Language Support

By default all APIs return error messages and textual information in English.
To run an API with another language include the 'lang' parameter with a 2 letter code of the language. E.g. for French: ...&lang=fr
Note that only languages which are enabled in Alma can be used (according to 'Institution Languages' mapping-table).
 

Error Handling

In case of an error, a HTTP  4XX or 5XX error will be returned as well as a response describing the type of the error: 

A logical error (e.g. user identifier does not exist) will return 400 HTTP response, as well as something like the following:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<web_service_result xmlns="http://com/exlibris/urm/general/xmlbeans">
  <errorsExist>true</errorsExist>
    <errorList>
    <error>
      <errorCode>401861</errorCode>  
   <errorMessage>User with identifier abc123 was not found.</errorMessage>
   <trackingId>E08-3003073344-FVK4V-AWAE1845814992<trackingId>
       </error>
     </errorList>
</web_service_result>

An internal server error (e.g. the DB is down) will return HTTP 500, as well as message such as the following:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<web_service_result xmlns="http://com/exlibris/urm/general/xmlbeans">
  <errorsExist>true</errorsExist>
  <errorList>
    <error>
      <errorCode>INTERNAL_SERVER_ERROR</errorCode>
      <errorMessage>The web server encountered an unexpected condition that prevented it from fulfilling the request.</errorMessage>
      <trackingId>E01-2303131047-FGBKX-TSE188753689</trackingId>
    </error>
  </errorList>
</web_service_result>
Error message XSD - the schema for the XML returned when receiving an error
 

Input and Output Formats: XML and JSON

The input and output of Alma RESTful API can be in XML or JSON formats.
The output is determined by either:
An Accept header: Accept: application/json
Query param: .https://..?apikey=XXX&format=json
The default is XML.
When sending XML as an input add the following header: Content-Type: application/xml
When sending JSON as an input add the following header: Content-Type: application/json
 
 
see also the How we're building APIs at ExLibris blog entry for more useful information.
 
 

For the Organization Admin: Inviting developers

  1. Log in with your organizational admin credentials*.
  2. In the API dashboard left pane, choose Organization - Invitations:
  1. You can invite the rest of the developers in your institution to join the portal, by specifying their email addresses.
  2. After they have accepted your invitation, you will be able to see the list of your institution’s developers under Organization - Developers.

* If you wish to give organizational admin rights to another user, please open a support ticket.

 

API Governance Thresholds

We want developers to create compelling applications and integrations, but we also want the Alma service to always provide the best experience possible for its users.
 
To maintain optimum performance and ensure that infrastructure resources are not disproportionately used in an inefficient manner, Alma has Governance Thresholds in place. Governance thresholds ensure that no single institution negatively impacts other Alma institutions, prevent performance degradation and can help reduce the risks of malicious attacks.
 
For APIs, Alma has two types of governance thresholds:
  • Daily API Request Threshold
  • Concurrent API Request Threshold
Ex Libris designed the API governance thresholds after extensive analysis of real customer scenarios and we expect the thresholds to be high enough that reasonable use of the APIs should not exceed the thresholds. See also our Reducing the number of API calls article.
 
In the dashboard available via the Ex Libris Developers Network, you can view statistics about your API usage. The number of remaining requests is also available in a header: X-Exl-Api-Remaining.
Since each request made to the API incurs a computational cost, it’s important to make economical use of API requests. If a common function of your application can be performed using fewer requests than it currently does, it should.

Daily API Request Threshold

The Daily API Request Threshold permits 1000 API calls per number of named user licenses per day (the threshold is not per-user basis - it is enforced against the aggregate of all API calls made by the institution in a 24 hour period). For example, for an institution with a 100 named users license, the Daily API Request Threshold is 100,000 requests (100 named users X 1000 calls = 100,000 daily requests). If the number of API requests exceeds the daily threshold, an error is returned for any additional API requests:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<web_service_result xmlns="http://com/exlibris/urm/general/xmlbeans">
  <errorsExist>true</errorsExist>
  <errorList>
    <error>
      <errorCode>DAILY_THRESHOLD</errorCode>
      <errorMessage>Daily API Request Threshold has been reached. For details see: https://developers.exlibrisgroup.com/alma/apis#threshold</errorMessage>
      <reason></reason>
    </error>
  </errorList>
</web_service_result>
The caller will have to retry these API requests the next day. Note that end of the day is midnight GMT.
If there is a special and urgent need to enable APIs contact Ex Libris 24X7 HUB.
 

Concurrent API Request Threshold

The Concurrent API Request Threshold permits up to 25 API calls per institution per second. This threshold applies to all API requests to the Ex Libris API gateways.
API requests exceeding the Concurrent API Request Threshold will be blocked with the following error (HTTP code 429):
 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<web_service_result xmlns="http://com/exlibris/urm/general/xmlbeans">
  <errorsExist>true</errorsExist>
  <errorList>
    <error>
      <errorCode>PER_SECOND_THRESHOLD</errorCode>
      <errorMessage>HTTP requests are more than allowed per second. See https://goo.gl/2x1c1M </errorMessage>
    </error>
  </errorList>
</web_service_result>
 
Applications which receive the above error should take steps to reduce concurrent usage.
 

Alma APIs FAQ

I'm an existing Alma customer, how do I gain access to my Alma environment in the Developer Network?

We will begin allowing access to institutional environments via the Developer Network with the June release. At that time we will provide institutional logins to every existing customer. 
 

I'm not an Alma customer, can I still try out the APIs?

Yes. Simply create an application in the Dashboard and leave the API Plan for the APIs you want to try assigned to the "Guest Sandbox" API Plan. Using the Application's API key you will be able to run read-only requests against our Demo server.
 

How do I migrate my existing application to the Alma Developer Network?

Change the URL from Alma's server to the API Gateway and instead of the Basic Authentication user & password add the API-key as a parameter or a header.