Overview and workflow

This document describes a suggested workflow for integrating external services with ReShare using ReShare APIs. Note that this approach is based on the current capabilities of the system, and this documentation will be updated as improved functionality is introduced.

...

1. A user places an interlibrary loan request in an external system.

2. The external system uses the ReShare Shared Inventory API to identify an eligible instance.

   1. Search by bibliographic metadata, such as ISBN, title, author.

   2. Identify a matching instance record.

   3. Confirm that this instance record has at least one holding with an ILL status of “Will lend.”

   4. Return the UUID of the Instance.

3. The external system uses the ReShare OpenURL resolver to create a new request.

   1. The OpenURL must include the Instance UUID identified from the shared inventory.

   2. The OpenURL must include a patron ID of the same type that ReShare is using for verification with a particular library.

   3. The OpenURL resolver will return a confirmation of success and the UUID of the request in the library’s ReShare tenant.

4. The external system uses the ReShare mod-rs API for each individual library tenant to poll for the status of the request using the UUID returned by the OpenURL resolver.

Required data

To complete the processes described in this document, you will need the following values. These values can be provided by the library and/or its service provider.

...

Pickup location mapping: Libraries must provide a mapping between all pickup locations used in the external ILL service and the slugs associated with each pickup location in ReShare. The external ILL service will need to use this mapping to identify the slug needed to set the “svc.pickupLocation” parameter in  the OpenURL.

Shared Inventory API

The shared inventory API allows searching by bibliographic data to identify records held by the consortium. The primary use cases for the API in the context of ReShare integration include identifying an eligible instance record for a request and capturing the UUID of that instance.

Additional documentation

Searching is done using GraphQL queries. Additional documentation on these queries can be found at: https://github.com/folio-org/mod-graphql/blob/master/doc/example-queries.md

Notes

The shared inventory harvests and aggregates data from many library catalogs using a match key algorithm. Duplicates are not uncommon, and it is possible a query based on bibliographic data may return more than one matching title in the shared inventory. In this situation, you may choose to either return the request for user review or develop a method for choosing a record from among the results, such as choosing the instance with the most available holdings.

Sample queries

This example uses curl to perform a title search in the shared inventory. Begin by obtaining a token for the shared index API following the instructions in the appendix.

...

Note, it’s possible that you’ll receive the error curl: (92) HTTP/2 stream 1 was not closed cleanly: PROTOCOL_ERROR (err 1) on this call, if that is the case, force curl to use http1.1 by adding the --http1.1 option.

OpenURL resolver

ReShare uses an OpenURL resolver to initiate requests from outside the system. At the current time, the resolver only supports requests for known items and you must include the unique ID of a shared inventory record, which can be identified using the Shared Inventory API described above.

Additional documentation 

Full documentation for the OpenURL resolver can be found at: https://github.com/openlibraryenvironment/listener-openurl/blob/master/doc/openurls-for-reshare.md

Notes

Constructing a base URL

• Each ReShare consortium will have its own base URL. 

• This URL must be followed by the OpenURL Tenant ID of the institution to which the requester belongs. This will ensure the request is directed to the right tenant.

• Example: https://listener-openurl.folio-dev.indexdata.com/US-EAST.

...

• Pickup location (svc.pickupLocation): Code must match the slug of a pickup location directory entry in the requesting library’s ReShare Directory.

• Shared Inventory UUID (rft_id): You must include the UUID of a shared index record, which can be found using the shared index API as described above.

• Patron ID (req_id): If you are using NCIP, this value must be the identifier (for instance, barcode) for a valid patron in your library’s local ILS. Otherwise, it can be any value.

Sample OpenURL

Line breaks are used in this sample to increase clarity.  This OpenURL contains these required values:

...

https://listener-openurl.folio-dev.indexdata.com/US-EAST?
svc.pickupLocation=linderman-test&
svc.neededBy=2021-09-17&
rft.volume=1&
svc.note=Test&
ctx_enc=info%3Aofi%2Fenc%3AUTF-8&
ctx_ver=Z39.88-2004&
req_id=2505428762917384&
rfr_id=...meaningful-referrer-identifier-descriptor…&
rft.au=Steffens%2C+Lincoln%2C+1866-1936&
rft.creator=Steffens%2C+Lincoln%2C+1866-1936&
rft.date=%5B%C2%A91935%5D&
rft.format=UnknownFormat&
rft.pub=Harcourt%2C+Brace%2C&
rft.title=Boy+on+horseback&
rft_id=83b9a3a2-efc0-4cb4-977f-c6c7ca39f976&
rft_val_fmt=info%3Aofi%2Ffmt%3Akev%3Amtx%3Adc&
svc.ntries=1&
url_ver=Z39.88-2004

mod-rs API

Mod-rs is ReShare’s resource sharing module. The mod-rs API can be used to return the current state for a given request. 

Notes

Each request in ReShare has two types of identifiers.

...

• Expects to supply: A supplier has been assigned and plans to provide the item

• Shipped: The supplier has shipped the item to the requester.

• Return shipped: The requester has returned the item to the supplier.

• Complete: The supplier has received the returned item and closed the request.

• End of rota: No supplier could be identified and the request cannot be filled.

• Cancelled: The requester has cancelled the request.

Sample query

Begin by getting an API token following the instructions in the appendix.

...

$ curl \
  -H "X-Okapi-Tenant: $TENANT" \
  -H "X-Okapi-Token: $TOKEN" \
  $OKAPI_URL/rs/patronrequests/b4f9c7fc-5fdb-49eb-bf9b-1faab4d3a5bd 

Appendix: Getting an API token

Both the Shared Inventory and mod-rs run on the Okapi platform and share a common method of logging in. Note that the Shared Inventory and the mod-rs tenant of a specific library have distinct “X-Okapi-Tenant” values. The following example shows how to obtain an API token using cURL.

...