Token Based Anonymous Access For OPDS Feeds
EBC provides APIs for the Catalog Manager to pull book lists to surface to the SimplyE Patron via the Circulation Manager. EBC also provides APIs to request a download link for a Patron to ultimately retrieve the book directly from EBC via the ACS fulfillment fulfilment URL.
This document describes general requirements for using these External Partner APIs.
Prerequisites
- Patron should be Authenticated with NYU Library first before accessing the OPDS Feeds since Authentication is done outside of the ProQuest EBC Platform.
- SAML Integration: SimplyE authenticates with NYU before accessing the OPDS Feeds.
- Token Based Anonymous Access: This service is introduced since SimplyE doesn't directly authenticate with ProQuest EBC Platform.
API Security
ProQuest APIs will only be accessible from a set of whitelisted IPs. Users of those APIs will also be required to provide a JWT.
IP Whitelisting
To gain access to the ProQuest APIs, you'll need to submit your IP Address (or addresses) via email to Umamaheswara Gandluru (Umamaheswara.
Gandluru@proquest.com). Please indicate which environment (Test or Production) should be associated to the given IPs.
Token Based Anonymous Access
ProQuest requires a JWT (JSON Web Token) Token in a self-contained way for securely transmitting information between parties as a JSON
object. JWT Tokens are useful in Authorization and Information Exchange between two parties. This Token is required as an Authorization header
for all OPDS Feeds.
How to obtain a token
Please see the PartnerAuthToken service definition below.
...
The token value must be supplied as HTTP request header.
| Header Name | JWT Bearer Token as an Authorization Header Authorization: Bearer <JWT Token> |
|---|---|
| Header Value | The JWT token returned from the PartnerAuthToken service |
ProQuest Environments
| Current Prod-Setup Test Environment (T) | https://ebookcentral-t.ebrary.com |
|---|---|
| Future Prod-Setup Test Environment (J) | https://search.pre.proquest.com |
| Production | https://ebookcentral.proquest.com |
ProQuest Services
Common API Response Codes
| Status | Status Code | Status Message |
|---|---|---|
| 200 | OK | Successful JSON Response |
| 500 | error | Expired or invalid JWT token |
| 400 | Bad |
...
| Request | N/A | |
| 404 | NOT_FOUND | No Documents Found |
| 500 | error | Invalid page error:<pagenumber> Invalid hits per page error:<number> |
Service Definitions
Service:
...
BooksCatalog
...
This service returns a paged ProQuest's OPDS 2.0 feed. Please note that it returns a JSON document with the feed stored as one of its properties.
This service is IP Authenticated and doesn't require authentication.
Service: BooksCatalog
This service is IP Authenticated with Anonymous Access (which will be done in HQ). Generates OPDS Feed in JSON Format.
Method: GETURL: https://<Env Specific Domain>/lib/nyulibrary-ebooks/BooksCatalog?page=1&hitsPerPage=10
Parameters:
page= Default = 1 (MaxLimit = 32767)hitsPerPage= Default = 10 (MaxLimit = 32767)
Example Response: BooksCatalog.json
Service: BookshelfCatalog
:
| Code Block |
|---|
{
"statusCode": 200,
"statusMsg": "OK",
"opdsFeed": "<OPDS 2.0 feed>"
} |
Service: PartnerAuthToken
Creates a new user if doesn't exists in ProQuest Platform. Generates JWT Token in a This service takes JWT Bearer Token as an Authorization Header. Generates OPDS Feed in JSON Format.
Method: GET
URL: https://<Env Specific Domain>/libauth/ws/auth/PartnerAuthToken/nyulibrary-ebooks/BookshelfCatalogExample Response: BookshelfCatalog.json?userName=<AffiliationID>
Parameters:
AffiliationID= This should match ID with SAML Authenticated User ID
Example Response
| Code Block | ||
|---|---|---|
| ||
{
"statusCode": 200,
"statusMsg": "OK",
"token": "eyJhbGciOiJIUzI1NiJ9. eyJzdWIiOiJtYWhlc2hnIiwiaXNzIjoiUHJvUXVlc3QiLCJhdWQiOiJTaW1wbHlFIiwiaWF0IjoxNjAyNzk0Mjg1LCJleHAiOjE 2MDI3OTc4ODV9.X_uWRv_IZXqAPllWW6CNMcU2aILVbQBUsDHfyjeHrdA"
} |
Service: DownloadLink
This service takes JWT Bearer Token as an Authorization Header.
For DRM Protected Titles:
returns a book for particular ProQuest's document ID (unique book's identifier in the ProQuest's platform).
Method: GET
URL: https://<Env Specific Domain>/lib/nyulibrary-ebooks/DownloadLink?docID=<document ID>
Parameters:
docId= The EBC document ID
...
Example Response
...
Depending on the book type this service can return different types of response:
- for open-access book the service returns book's binary content as is
for Adobe DRM protected books the service returns a link to an ACSM file which you need to hit again to get the actual ACSM file:
Code Block { "statusCode": 200, "statusMsg": "OK" "downloadLink": "http://<Env Specific Domain>/fulfillment/URLLink.acsm?
...
action=enterloan&ordersource=ebl&orderid=492193_217274394&resid=urn%3Auuid%3AE0000000-0000-0000-
...
0000-000000492193&gbauthdate=Thu%2C+15+Oct+2020+04%3A44%3A55+-0400&dateval=1603982695&rights=%
...
24lrt%2386398%24%24cpy%230%2386398%24%24prn%230%2386398%
...
24&gblver=4&auth=e7ccf800938b6233900d012be62d91f70cdb88bd",
...
}