Bug 37640 - Allow patron REST API endpoint to accept cardnumber instead of borrowernumber
Summary: Allow patron REST API endpoint to accept cardnumber instead of borrowernumber
Status: CLOSED INVALID
Alias: None
Product: Koha
Classification: Unclassified
Component: REST API (show other bugs)
Version: Main
Hardware: All All
: P5 - low enhancement
Assignee: Aleisha Amohia
QA Contact: Testopia
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2024-08-13 23:18 UTC by Aleisha Amohia
Modified: 2025-06-02 20:46 UTC (History)
3 users (show)

See Also:
GIT URL:
Initiative type: ---
Sponsorship status: Sponsored
Comma delimited list of Sponsors:
Crowdfunding goal: 0
Patch complexity: Small patch
Documentation contact:
Documentation submission:
Text to go in the release notes:
This enhancement adds a new system preference RESTPatronIDField. It is set to borrowernumber by default, to support the standard behaviour of providing a borrowernumber to the Koha REST API endpoints to identify a patron. When the syspref is set to cardnumber, Koha will identify the patron using a provided cardnumber and not match on borrowernumber at all. This is useful in cases where organisations may want to use the API endpoints to do patron actions, but don't have the borrowernumber, as this is a unique ID generated within Koha. Note: it's possible that giving a borrowernumber when the API endpoint is expecting a cardnumber will still return results, and vice versa - if your cardnumber is an integer and happens to also be a borrowernumber. It's important in this case that only one or the other is used to ensure expected results.
Version(s) released in:
Circulation function:


Attachments
Bug 37640: Allow patron REST API endpoint to accept cardnumber (7.58 KB, patch)
2024-08-14 04:15 UTC, Aleisha Amohia
Details | Diff | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description Aleisha Amohia 2024-08-13 23:18:56 UTC
patron_id as borrowernumber is not always accessible to the organisation trying to use a Koha REST API endpoint for patrons. They are likely however to have the cardnumber, and it would be useful to be able to find patrons with that.
Comment 1 Aleisha Amohia 2024-08-14 04:15:40 UTC
Created attachment 170303 [details] [review]
Bug 37640: Allow patron REST API endpoint to accept cardnumber

This enhancement adds a new system preference RESTPatronIDField. It is set to borrowernumber by default, to support the standard behaviour of providing a borrowernumber to the Koha REST API endpoints to identify a patron.

When the syspref is set to cardnumber, Koha will identify the patron using a provided cardnumber and not match on borrowernumber at all.

This is useful in cases where organisations may want to use the API endpoints to do patron actions, but don't have the borrowernumber, as this is a unique ID generated within Koha.

To test:

1. Create a patron in the staff interface. Take note of their borrowernumber. Set the cardnumber to something - a string or an integer - and take note of this too.
2. In another tab, go to the API endpoint for getPatron your OPAC URL/api/v1/patrons/{patron_id}
3. Replace {patron_id} in the URL with the borrowernumber. Confirm your patron's data is returned successfully.
4. Replace {patron_id} in the URL with the cardnumber. Notice an error is thrown.

5. Apply the patch. Install database updates. You may need to regenerate the API spec to make the API changes take effect: https://wiki.koha-community.org/wiki/Rest_Api_HowTo#Step_7:_Regenerate_API_spec . Then restart services.
6. In the staff interface tab, go to Koha Administration -> system preferences. Search for the new preference RESTPatronIDField. Notice it is set to borrowernumber by default.
7. In your API endpoint tab, again replace {patron_id} in the URL with the borrowernumber. Confirm your patron's data is returned successfully.
8. Change the RESTPatronIDField system preference to cardnumber and save.
9. Refresh your API endpoint tab. Replace {patron_id} in the URL with the cardnumber. Confirm your patron's data is returned successfully.

Note: it's possible that giving a borrowernumber when the API endpoint is expecting a cardnumber will still return results, and vice versa - if your cardnumber is an integer and happens to also be a borrowernumber. It's important in this case that only one or the other is used to ensure expected results.

Sponsored-by: Chartered Accountants Australia and New Zealand
Comment 2 David Cook 2024-08-14 05:53:44 UTC
Comment on attachment 170303 [details] [review]
Bug 37640: Allow patron REST API endpoint to accept cardnumber

Review of attachment 170303 [details] [review]:
-----------------------------------------------------------------

::: api/v1/swagger/paths/patrons.yaml
@@ +487,4 @@
>        - name: x-koha-embed
>          in: header
>          required: false
> +        description: Embed list sent as a request header hello

I'm guessing the addition of "hello" here is a mistake?
Comment 3 David Cook 2024-08-14 05:54:39 UTC
Overall, I don't think this is a good idea. It goes against the REST idea. 

You can search for the patron using the cardnumber, and then use the borrowernumber. Is that undesirable because it's twice as many steps?
Comment 4 Martin Renvoize (ashimema) 2024-08-14 07:34:59 UTC
Why not just use the API as intended and search using the cardnumber param?


GET /api/v1/patrons?cardnumber=X

I don't like this change at all.. you'd need to also update all occurrences in the staff client where the API is expecting the actual ID in the path.
Comment 5 Katrin Fischer 2024-08-14 07:35:15 UTC
Hm, wondering about this one. 

We also have the case that the external partner doesn't know the patron_id, so we use listPatrons and query by cardnumber, which returns only one patron's information. This way we only need one query to get the information we need and the patron_id to use in further requests.

Do we risk breaking things where Koha uses the API internally? Cardnumber isn't a mandatory field necessarily.

There are also other routes where the patron_id would still be required, like when looking up checkouts or placing holds. I feel it might make things a little more inconsistent.

Small typo here:

-        description: Embed list sent as a request header
+        description: Embed list sent as a request header hello
Comment 6 Martin Renvoize (ashimema) 2024-08-14 07:36:53 UTC
Search for "patrons/" accross the codebase and you'll find there's a large number of requests already using "/patrons/{patron_id}"
Comment 7 Aleisha Amohia 2024-08-14 21:13:26 UTC
(In reply to Martin Renvoize from comment #4)
> 
> GET /api/v1/patrons?cardnumber=X
> 


Thanks all. I'm happy to close this - was just exploring the request from the library and with this much pushback, it's clearly not the direction the community wants to go in. All good :)

Thanks Martin for this cardnumber search syntax, I'll suggest they use this.