REST APIs

Alma REST APIs provide access to data and workflows stored in Alma. The Developer Network is your key to getting the most out of these APIs. On the following pages, you’ll find documentation for each of the interfaces, including a full description of the parameters and the data objects.

Getting Started with Alma APIs

You can view all of the documentation and try out the APIs without logging in to the Developer Network. To use the APIs to access your institution’s data, you’ll need a Developer Network account.

This short video walks you through the process of using the Alma REST APIs with the Developer Network:

The following sections describe how to use the features of the Developer Network and the Alma APIs.

• Developer Network Accounts
• Using the Alma REST APIs
  • API Keys
  • Permissions
  • Calling Alma APIs
• Using the API Console
• About Alma APIs
  • Structure of the REST URIs
  • Versioning
  • Language Support
  • Error Handling
  • Input and Output Formats: XML and JSON
• Managing Users in Your Institution
• API Governance Thresholds
• OpenAPI Support
• Planned block of TLS 1.0 and 1.1 traffic
• Alma APIs FAQ

Developer Network Accounts

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. Click the signup link in the top menu bar.
   
2. The registration form appears:
   
3. Fill in the required personal information, click I have read and agree to the Terms of use and Privacy Policy, and click Register. An email message with an activation link is automatically sent to you.
4. In the email message that you received, click the link to activate your account.
5. Congratulations! You now have a Developer Network account and can use our APIs, write a question in a forum, and add blog posts.

Using the Alma REST APIs

In the following sections we’ll show how to get started using the Alma REST APIs.

API Keys

To use an Alma API with an external application, you have to create an API key:

1. 1. On the top menu, click “Build – My APIs.” Then select ”MANAGE KEYS”:
      
   2. At the bottom of the list, click Add API Key.
      
   3. Add the relevant application information. The following fields are available:
      • Name – logical identifier for the API key/application (required)
      • Description – logical description of the key/application
      • Enabled – indicates if the API key is enabled or disabled
      • Save detailed log files – when enabled, the platform will save detailed log files for any API requests using the API key and make them available in the Reports -> History tab for one week. The setting is retained for 3 months and can be reset if necessary.
      • Allowed IP Range – optionally limit the IP range from which API calls are permitted with the key. Must be in CIDR format. Online IP to CIDR converters such as this one are available online.
      • Restriction Profile Code – can be used to further limit the data available using the API key. For a detailed explanation, see here.
      • Permissions – at least one is required

      

   4. The selected API key will appear after clicking on ‘save‘.
      An API key is necessary for authenticating API requests. You must include it as a parameter in the URL when calling an Alma API. See Calling Alma APIs below.

Permissions

You can define permissions for each API key. The following properties apply when adding a new API permission:

• Area: The functional area for which access is to be granted, i.e. “researchers”
• Environment: The environment to grant access to, i.e. Guest Sandbox, Sandbox, or Production
• Permission: Read-only or read/write.

It is recommended that you test an API against a sandbox environment first. Later on, you can update the API to work against a production environment.

To add permissions to an API key, follow these steps:

1. Click the “add permission” button.
2. Select the functional area
3. Select the environment
4. Select the permission
5. Save the API key

Important note: Changing configuration for an API-key (“Application”) in the Dashboard might take a few minutes until it becomes available for use.

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:

When you call an Alma API, you must provide the API key to authenticate the request. The API key can be provided as a URL parameter, for example:

https://api-na.hosted.exlibrisgroup.com/almaws/v1/users?apikey=lx7abcdefghijklmnop

Alternatively, you can send the API key as an Authorization header as follows:

Authorization: apikey {APIKEY}

Note that your application should connect to the API gateways only via HTTPS using TLS 1.2.

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.

Note: If you have reached the API console from the Try It Now button, the API is already selected, so skip to step 2.

To use an API through the API console:

1. Select an API from the list:
   
2. Now you can select a resource and a method from the list below:
   
3. The API request form appears. It includes the parameters relevant to the specific API, and default values:
   
4. You can click on Try it out to change the default values.
5. Submit the API request by clicking Execute.
   
6. The response is displayed below in Responses, along with the request as it can be called from curl.
   

Note that only GET requests are permitted in the guest sandbox.

About the Alma REST APIs

To learn about the structure of Alma REST APIs, see the article “How We’re Building APIs at Ex Libris“.

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 – this means that the entire existing entity will be replaced with the incoming entity. Calling applications are expected to run a GET before PUT, and send the entire entity with the relevant fields modified. Missing fields will be given default values.)
• 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 parameters 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 (here in JSON, when the request was send with format=json):

{
    "errorsExist": true,
    "errorList": {
        "error": [
            {
                "errorCode": "401861",
                "errorMessage": "User with identifier 1234 was not found.",
                "trackingId": "E01-0101190932-VOBYO-AWAE1554214409"
            }
        ]
    },
    "result": null
}

An internal server error (e.g. the DB is down) will return HTTP 500, as well as message such as the following (here in XML, when the request was send with format=xml):

<?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/JSON returned when receiving an error.

Gateway error codes

The gateway’s errors are always in XML. The following errors might be returned by the Gateway on initial client-side setup:

The following errors might be returned by the Gateway on special cases:

Input and Output Formats: XML and JSON

The input and output of Alma RESTful API can be in XML or JSON formats.

Output

The output is determined by either:

• An Accept header: Accept: application/json
• Query param: https://..?apikey=XXX&format=json

The default is XML.

JSON output may slightly differ from XML:

1. Arrays in XML are enclosed in an element with the name in plural: <users><user>…</user></users> while in JSON we only have the singular name: user: [ {}, {}, … ]
2. Fields without useful value which are omitted from the XML might appear as “null” in JSON output.

Input

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

Note: When the API’s payload includes MARCXML the API will not support JSON as input. This includes the Update/Create Bib/Holdings APIs.

See also:

• How we’re building APIs at ExLibris blog post
• API tips for beginners blog post

Inviting developers to your institution

1. Log in with your organizational admin credentials*.
2. On the top menu, click “Build – My APIs.” Then select “USERS” in “Manage Users”.
   
   ?* If you wish to give organizational admin rights to another user, please open a support ticket.
3. You can invite the rest of the developers in your institution to join the portal, by specifying their email addresses.
4. After they have accepted your invitation, you will be able to see the list of your institution’s developers under Organization – Developers.

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 (My APIs->Reports). 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>
    </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.

OpenAPI Support

The OpenAPI specification provides a standard way of describing REST APIs.

The OpenAPI Specification, originally known as the Swagger Specification, is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services.

Wikipedia

Support for OpenAPI is being rolled out for Alma REST APIs. Read the blog posts and keep an eye out for more updates.

Planned deprecation of TLS 1.0 and 1.1 traffic

TLS is a cryptographic protocol that provides authentication and data encryption between different endpoints (for example, the user’s desktop and the application server). Various vulnerabilities (such as POODLE and DROWN) have been found in TLS versions 1.0 and 1.1 in recent years.
As announced in the latest security update, to avoid security vulnerabilities and to align with industry standards, Ex Libris will block TLS 1.0 and 1.1 traffic for Alma API in production environments and will support only TLS 1.2.

Alma APIs FAQ

I’m an existing Alma customer, how do I gain access to my Alma environment in the Developer Network?
You should have received a Developer Network account with access to your Alma environment. If you have not received the credentials, contact your project team or support.

I’m not an Alma customer, can I still try out the APIs?
Yes. Simply visit the API Console and try them out. You can also try out the APIs in your own application. Note that the APIs will be submitted against our guest sandbox, in which only GET requests are permitted.