REST

Primo RESTful APIs provide access to information stored in Primo. The Developer Network is your key to getting the most out of these APIs. In the Developer Network 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 into 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 a Primo institution, please contact your institution’s technical administrator in order to get an invitation to join the institution’s 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 Primo customer and would like to try out our APIs, you can create an account and use the APIs against our Guest Sandbox.

To sign up, follow the steps below:

1. 1. On the API Portal home page, click Signup in the upper right-hand corner:

1. 1. The registration form will display. Fill in the required personal information; accept the Terms of Use and click Register Now.

3. You will receive an email with an activation link.
4. After pressing this link, your account is activated.

Congratulations! Now you have a Developer Network account and can start using our APIs.

Using Primo APIs

Defining an application

For each external application that will use the Primo API, an Application should be defined in the portal:

1. In the left-hand menu, choose “Applications:”
   
2. Click Add Application. This displays a wizard with tabs:
   
3. Add the relevant application information in the Application Information tab. Only Application Name and Platform are required.
4. In the API Management tab, list the APIs currently used by the application.  To add an API:
   • Choose the API from the drop-down list.
   • Read the terms of use and accept them.
   • The selected API displays under Current APIs.
   • To remove the API, click the trash-can icon. Add additional APIs as necessary.
   • Click Save when done.
5. You will see that your application was created along with its assigned API key:
   

The API key will be used to authenticate the API requests. It must be included as a parameter in the URL when calling Primo APIs, e.g. apikey=iyr4h238r4. See Calling Primo APIs.

1. 1. You can now use the API Key to make API calls against the Guest Sandbox.
   2. To point the API key to your own environments, click the gear wheel to edit the API:

1. 1. Environment access is controlled by API Plans. In addition to the guest sandbox, four API Plans are available: read only and read/write for your sandbox environment and read only and read/write for your production environment. Select an API Plan for each of the APIs:

We recommend that you initially use APIs against a sandbox environment for testing. The APIs should later be updated to work against a production environment.

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:

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.

The Developer Network also includes an API Explorer which you can use to test additional Primo APIs. You can access the API Explorer here: https://developers.exlibrisgroup.com/alma/api-explorer.

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.

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 the Primo RESTful API is in version 1. If we add optional parameters to the URL or tags and attributes to the returned data – we will still consider it to be v1. If we need to remove or rename tags or change the behavior of an existing URL, 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.

For the Technical Administrator: Inviting developers

1. In the API dashboard left pane, choose Organization – Invitations:
2. 
3. 2. You can invite the other developers in your institution to join the portal, by specifying their email addresses.
   3. 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
   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. The caller will have to retry these API requests the next day.
   The Concurrent API Request Threshold permits up to 10 API calls per institution per second. This threshold applies to all API requests to the Ex Libris API gateway. API requests exceeding the Concurrent API Request Threshold are automatically queued and processed in the order in which they are received. (Note that the overall API response time for requests that are queued will be slower.)
   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. 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.

   Primo APIs FAQ

   I’m an existing Primo customer. How do I gain access to my Primo environment in the Developer Network?

   If you are a developer at a Primo institution, please contact your institution’s technical administrator in order to get an invitation to join the institution’s group. Once you have joined your institution’s group, you will be able to create and edit your institution’s applications.

    

   I’m not a Primo customer. Can I still try out the APIs?

   Yes. Simply create an application in the Dashboard and assign it 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 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.