Primo REST APIs

NAVIGATE CONTENT
Ex Libris Developer Network Primo Documentation Primo REST APIs

Primo REST APIs provide access to data and workflows stored in Primo. 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 Primo REST APIs

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

Developer Network Accounts

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

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

API Keys

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

    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.
    4. The selected API will appeared after clicking on ‘save‘To add more APIs, repeat the process.
    5. Your application is defined and is assigned an API key:
      [image]
    6. An API key is necessary for authenticating API requests. You must include it as a parameter in the URL when calling a Primo API. See Calling Primo 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. “users”
  • 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.

 

Note: To complete the registration process to the API gateway, please open a Salesforce case with the following information:

  • Title – “Primo RestFul API registration”
  • In the description please include the following information:
    • Organization name as you entered in the developer network registration.   
    • Your Primo URL that the API gateway will work with.
    • Primo institution code.

Once Ex Libris support will complete the registration process, you will be able to start develop using the API gateway.

 

Calling Primo APIs

The REST style allows you to call Primo APIs from a variety of development environments and even from your browser.

In your external application, a call to a Primo API should be directed to the API gateway in your region:

RegionURL
North Americahttps://api-na.hosted.exlibrisgroup.com
Europehttps://api-eu.hosted.exlibrisgroup.com
Asia Pacifichttps://api-ap.hosted.exlibrisgroup.com
Canadahttps://api-ca.hosted.exlibrisgroup.com
Chinahttps://api-cn.hosted.exlibrisgroup.com.cn

 

The API key must be included as a parameter in the URL when calling Primo APIs, e.g. apikey=iyr4h238r4. The API key will be used in order to authenticate the call and direct the request to the relevant institution and the relevant environment (sandbox/prod) according to the defined API Plan.

If you prefer sending the API key as a header instead of in the URL you can do so using the following syntax:

Authorization: apikey {APIKEY}

To try out your newly created API key, you can make a simple call in a browser to the gateway as indicated above with the following added to the end of the URL: /primo/v1/pnxs?apikey=XXXXX. You should receive a list of the PNXs defined in the guest sandbox or in your institution, depending on the configuration of the API key.

If you’ve built an application using our SOAP/XService APIs, you don’t have to make any changes yet. We will publish instructions for how to migrate those applications to new RESTful APIs in the future.

 

Using the API Console

The Developer Network’s API console enables you to test out the Primo 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.

About the Primo REST APIs

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

Primo REST APIs return CORS headers to allow calling them from JS code (AJAX). Pay attention not to expose API-keys in public client side applications.

Structure of the REST URIs

The standard HTTP method, GET, which retrieves a resource, will be used.

URIs for the Primo RESTful API resources have the following structure:

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

e.g. https://api-na.hosted.exlibrisgroup.com/primo/v1/pnxs?q=any,contains,book&?apikey=l7xx0804cb89d542

 

Versioning

Currently all of the Primo 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.

 

Resources

The current supported resources are: PNX records created from BIB records residing in Primo Central and Primo Local.

 

Error Handling

In the case of an error, an 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 an HTTP 400 response, as well as a message such as the following:

{

            "errorCode": 1234,

            "errorMessage":"Incomplete data"

            "details":[

                        {

                                     "errorCode":111,

                                     "errorMessage":"Missing name",

                                     "details":[]

                        },

                        {

                                     "errorCode":222,

                                     "errorMessage":"Missing address"

                                     "details":[]

                        }

            ]

}

 

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

{
            "errorCode": 1234,

            "errorMessage":"Internal Server Error"

            "details":[]
}

 

Input and Output Formats: JSON

The input and output of Primo RESTful APIs is in JSON.

 

Inviting developers to your institution

  1. Log in with your organizational admin credentials*.
  2. In the API dashboard left pane, choose Organization – Invitations:

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

For APIs, Primo 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 5 API calls per number of Full Time Equivalent (FTE’s) users licensed 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 30,000 FTE license, the Daily API Request Threshold is 150,000 requests (30,000 FTE’s X 5 calls = 150,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.

Each API request is restricted to a maximum of 2000 search results.

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.

Primo APIs FAQ

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

I’m not a Primo customer, can I still try out the APIs?
Yes. Simply visit the API Console and try them out. If you’d like to try out the APIs in your own application, create a guest account in the Developer Network. Then create an API key and add permissions for the Guest Sandbox. Note that only GET requests are permitted in the guest sandbox.

 

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

SaaS can change the URL to point to the API Gateway instead of to a Primo server and add the API-key as a parameter or a header instead of using the basic authentication username & password,.

 

I currently use SOAP APIs. Do I need to do anything?

Currently, no. We will announce in the coming months how and when you can route the SOAP requests via the API Gateway as well. In the meantime, continue sending them directly to Primo.