Go VE: Converting Primo APIs for Use in Primo VE

Last updated
Save as PDF
Share
1. Share
2. Tweet
3. Share

Primo VE uses REST API’s to expose some of Primo VE's core functionality for use by the library to integrate the data collected from the API’s to other services, thus adding functionality to their patrons.

This document highlights some of the differences to consider when creating new APIs for Primo VE and how to make Primo's APIs function properly when copied to Primo VE.

Background

API Configuration Differences in Primo VE

For each of the following areas, you may see a difference in your API's configurations:

Path – The internal path for Primo VE's API:

https://<base_url>/primaws/rest/pub

While Primo uses the following path:

https:// <base_url>/primo_library/libweb/webservices/rest/primo-explore/v1/ in Primo

You can user your browser’s developer tools Network tab to see if your code uses internal paths for the Primo APIs. If so, you will need to change the path. Any calls using the API gateway will not require any path changes:

<api-gateway-url>/primo/v1/<api-id>/<parameters>

For more information, see Primo REST APIs in the Ex Libris Developer Network.
Parameters – The vid parameter in Primo VE's API requests also includes the institution code—for example, ../configuration/vid/<inst_code>:<view_code>.
Responses – The structure of the API's responses are the same for both Primo and Primo VE, but some data (for example, the PNX search and browse sections) is not included because it is not used by Primo VE.

Documentation and Training

In preparation for this task, it is recommended that you familiarize yourself with the following documentation and training video:

Go VE - Become An Expert Series: Primo VE APIs (21 min)

Preparation: Check Your Primo API Usage

Review the possible usage of the APIs in your customization package or any other source code:

Edit your view on the View Configuration page in Primo VE (Configuration Menu > Discovery > Display Configuration > Configure Views) and download your customization package from the Manage Customization Package tab.
Review the custom.js file and any other code base that are using for your Primo APIs and look for references to the following in the code:
- $http (in angular) or the equivalent http client in other implemented technologies that represent an API call.
- primo_library
For each of the above references, check the URL call:
- If it’s an external call (not to the Primo server), do nothing.
- If it has a relative URL or a full path to the Primo domain, verify the following:
  1. The path and URL’s match the Primo VE structure for the same API
  2. Locate the equivalent API in Primo VE in the Developer Network.
  3. Check to see that the code parsing in the response is working well and not failing on data that no longer exists in the response.
  4. Remove or convert the code.
  5. Test to see that the functionality in the code snippet still works as expected.

Configuration: Conversion Examples

This section includes some examples that you may find useful to see what is needed to convert Primo API calls to Primo VE.

Go VE tip:

Before converting your code, re-examine your solution before copying it to Primo VE:

Is there a need for this functionality?
Is there a better implementation in the community or in Primo Studio?

Example 1: Usage of the search API:
1. In the following code snippet, change the marked URL:
  
  To the following path for Primo VE:
  
  /primaws/rest/pub/pnxs
2. Test the API to see that it returns the expected results.
Example 2: Parsing the API response:

In addition to changing URL definition, replace the recID assignment statement in the following code snippet since the search section is not returned in Primo VE responses:

With the following recID assignment statement, which now gets the record ID from the control section in Primo VE:

let recID = items[0].pnx.control.recordid[0];
Test the API to see that it returns the expected results.