| Summary: | Allow patron REST API endpoint to accept cardnumber instead of borrowernumber | ||
|---|---|---|---|
| Product: | Koha | Reporter: | Aleisha Amohia <aleisha> |
| Component: | REST API | Assignee: | Aleisha Amohia <aleisha> |
| Status: | CLOSED INVALID | QA Contact: | Testopia <testopia> |
| Severity: | enhancement | ||
| Priority: | P5 - low | CC: | dcook, martin.renvoize, tomascohen |
| Version: | Main | ||
| Hardware: | All | ||
| OS: | All | ||
| 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 | ||
|
Description
Aleisha Amohia
2024-08-13 23:18:56 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 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? 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? 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. 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 Search for "patrons/" accross the codebase and you'll find there's a large number of requests already using "/patrons/{patron_id}"
(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. |