Esploro REST APIs

Esploro REST APIs provide access to data and workflows stored in Esploro. 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 Esploro 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 Esploro REST APIs with the Developer Network:

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

• Developer Network Accounts
• Using the Esploro REST APIs
  • API Keys
  • Permissions
  • Calling Esploro APIs
• Using the API Console
• About Esploro APIs
  • Structure of the REST URIs
  • Versioning
  • Language Support
  • Error Handling
  • Input and Output Formats: JSON, XML (only Researchers, Analytics and Configurations)
• Managing Users in Your Institution
• API Governance Thresholds
• OpenAPI Support
• Esploro APIs FAQ

Developer Network Accounts

If you are a developer at an Esploro 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 Esploro 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 Esploro REST APIs

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

API Keys

To use an Esploro 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 information for Application Name and at least one Permission is required. Regarding Restriction Profile, see detailed explanation here.
      
   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 Esploro APIs

Esploro APIs are implemented in the REST style. This means that you can call Esploro APIs from a variety of development environments, and even from your browser. In your external application, a call to an Esploro API should be directed to the geographic location of your institution, as follows:

When you call an Esploro 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/esploro/v1/researchers?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 Esploro 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 Esploro REST APIs

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

Structure of the REST URIs

The Esploro 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 Esploro 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 Esploro 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 Esploro 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:

{
    "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, for supported APIs only):

<?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: JSON, XML (only Researchers, Analytics and Configurations)

The input and output of all Esploro RESTful API is JSON. XML is supported only for Researchers, Analytics and Configurations APIs.

Output

The output is determined by either:

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

Input

When sending JSON as an input add the following header: Content-Type: application/json
When sending XML (supported APIs only) as an input add the following header: Content-Type: application/xml

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 Esploro 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, Esploro has Governance Thresholds in place. Governance thresholds ensure that no single institution negatively impacts other Esploro institutions, prevent performance degradation and can help reduce the risks of malicious attacks.

For APIs, Esploro 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 50 API calls per number of academic staff 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 100 academic staff, the Daily API Request Threshold is 5,000 requests (100 academic staff X 50 calls = 5,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/esploro/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 Esploro REST APIs. Read the blog posts and keep an eye out for more updates.

Esploro APIs FAQ

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

I’m not an Esploro 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.