Table of Contents | ||||
---|---|---|---|---|
|
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.
...
A user places an interlibrary loan request in an external system.
The external system uses the ReShare Shared Inventory API to identify an eligible instance.
Search by bibliographic metadata, such as ISBN, title, author.
Identify a matching instance record.
Confirm that this instance record has at least one holding with an ILL status of “Will lend.”
Return the UUID of the Instance.
The external system uses the ReShare OpenURL resolver to create a new request.
The OpenURL must include the Instance UUID identified from the shared inventory.
The OpenURL must include a patron ID of the same type that ReShare is using for verification with a particular library.
The OpenURL resolver will return a confirmation of success and the UUID of the request in the library’s ReShare tenant.
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:
...
Code Block |
---|
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.
...
Each request will be assigned a state at any given time. A full list of possible states can be found at States .
For the purposes of integration, the states of greatest interest are those states that help determine the outcome of the request. These include:
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.
...
Code Block |
---|
$ 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.
...