Context

This document outlines the API changes for interaction between OPAC/Locate and FOLIO for multi-item requesting, including enhancements to existing endpoints as well as the introduction of new ones.

1 Working with allowed-service-points

When requesting a title or item, it is important to determine the service points that are allowed for the requested material and from which the patron selects the appropriate pickup service point. To support this behavior for single requests, the module edge-patron currently provides the following endpoints (as well as their modifications for secure patrons):

• GET /patron/account/{id}/item/{itemId}/allowed-service-points for item requesting,

• GET /patron/account/{id}/instance/{instanceId}/allowed-service-points for title requesting.

The response looks similar to this example:

For multi-item requests, it should also be possible to determine the allowed service points. According to the UX mockups, this should happen after selecting the items and pressing the “Add to list” button. This required outcome can be implemented in one of the following ways. It is proposed to implement this as follows: OPAC/Locate makes a single call, providing the list of selected item IDs; FOLIO replies with a JSON-format response with allowed service points information. Such a single call between OPAC/Locate and FOLIO minimizes the resource consumption.

Note that this can be implemented using either the GET or POST HTTP method. Assuming all item IDs (in the form of a UUID) are passed in the query string of the GET method, this introduces a limit on the number of item IDs in one request. The fact is that the query string size on FOLIO is limited to 8,000 characters (TBC), which for UUIDs allows approximately 50-60 elements. To implement a generic API, we should strive to avoid introducing this kind of technical limitation. So, we proceed with the POST method for this scenario.

Add a new endpoint with an array of all requested items:

• POST /patron/account/{id}/instance/{instanceId}/allowed-service-points-multi-item

Request body:

The structure of the Response body is quite similar - we make pairs of “item - list of service points” and collect these pairs into one array. Note that it’s still the responsibility of OPAC/Locate to process this information in any suitable way.

Other considered options:

• All efforts on the OPAC side - Minimum effort, but slow and taxing on the system. OPAC/Locate calls the existing edge-patron’s endpoint for each item separately, aggregates all the information, and then displays it on the UI.

• FOLIO groups a-s-p lists on its side - This appears to be a customization for Locate's current design and UX. Same endpoint as the proposed approach, but here FOLIO tries to figure out for itself how to group service points.

2 Creating a batch multi-item request

Creates a new batch request and returns a batchRequestId value. The batchRequestId value can be provided by the client or generated by the FOLIO.

A new endpoint must be created (in 2 modifications):

• POST /account/{id}/instance/{id}/batch-request (modification for regular patrons),

• POST /account/instance/{id}/batch-request (modification for secure patrons)

Request body:

200 OK Response body is returned if FOLIO has accepted the request and successfully persisted it for further processing:

If the request could not be parsed, saved, etc., the corresponding HTTP code should be returned.

When creating a single request, the response also contains information about the item (instance ID, item ID, title, and author), and also duplicates Patron notes - should this behavior be repeated for a batch request?

3 Retrieving the status and summary of a batch request

Returns the processing status of the batch request:

• GET /account/{id}/instance/{id}/batch-request/{batchRequestId}/status (modification for regular patrons),

• GET /account/instance/{id}/batch-request/{batchRequestId}/status (modification for secure patrons)

The response has almost the same structure as when a batch request was successfully created, with the key difference that it also contains itemsFailedDetails and itemsPendingDetails sections. The first of them provides extended information about the items for which the attempt to create an individual circulation request failed (including information about the item, plus the reason/description of the problem that arose when making the request). At the same time, another section contains information about items that are pending. This should allow OPAC/Locate to visualize both failed and pending items in the patron UI form(s).

See the response example below:

4 Getting all information about a batch and related requests

This part of the API is important so that clients can display information about multi-item requests on their side in an efficient manner. On one hand, we need a generic enough API to be used by different OPAC systems. On the other hand, Locate's UX mockups are the only thing we have right now.

Note: In its current functionality, the module mod-circulation provides a list of circulation requests created by a patron. This list will also, by default, include individual requests created for items from a multi-item batch. However - and this is important - 1) it is impossible to distinguish between single circulation requests and individual circulation requests, and 2) the list does not contain information about failed request creation attempts.

The new functionality solves this problem by enhancing the existing patron account API:

1. Adding an optional section batchRequestInfo to those individual circulation requests that are created from a batch,

2. Adding an optional section of batches to the response containing summaries for all batch IDs that appear in the request list.

Thus, the OPAC/Locate client needs to call one of the following Patron Services API endpoints by specifying a includeBatches=true parameter:

• GET /patron/account/{id} (modification for regular patrons),

• GET /patron/account (modification for secure patrons)

Below is an example of a response from FOLIO, containing both the familiar charges and loans sections, as well as the familiar holds section, in which some requests have a batchRequestInfo property, along with the new batches section. The batchRequestId makes it easy to match the request to the batch.

FOLIO backend hints

Below is a visualization of the FOLIO backend modules that will be used to process allowed service points and request list requests. Requests to create a multi-item request and retrieve its status will ultimately be processed in the mod-requests-mediated module.