Checkouts endpoint RFC

General overview

This RFC was voted on Development_IRC_meeting_13_March_2019

This RFC proposes several endpoints:

Checkouts

• /checkouts: for dealing with checkouts

Patron's checkouts

• /patrons/{patron_id}/checkouts: for fetching patrons's checkouts.

Checkout renewability

• /checkouts/{checkout_id}/allows_renewal: for getting a renewability status

Checkouts

Routes and actions

Description	Action	Proposed path	Implementation
List checkouts	GET	/checkouts	Bug 13895
Get a single checkout	GET	/checkouts/{checkout_id}	Bug 13895
Create a checkout	POST	/checkouts	Bug 23336
Update a checkout	PUT	/checkouts/{checkout_id}	Bug 24609
Return a checkout	DELETE	/checkouts/{checkout_id}
Find out checkout renewability	GET	/checkouts/{checkout_id}/allows_renewal	Bug 17003
Renew a checkout	POST	/checkouts/{checkout_id}/renewal	Bug 13895
Renew a checkout by patron (in opac)	POST	/public/checkouts/{checkout_id}/renewal

Object definition

DB schema	API	Description
issue_id	checkout_id	Internal checkout identifier
borrowernumber	patron_id	Internal identifier for the patron the checkout belongs to
itemnumber	item_id	Internal identifier for item related to the checkout
date_due	due_date	Due date of checkout
branchcode	library_id	Internal identifier for the library the checkout was from
returndate	checkin_date	Date the checkout was returned, in current checkout it is null
lastreneweddate	last_renewed_date	Date the chcekout was las renewed
renewals	renewals	The number of times the checkout was renewed
auto_renew	auto_renew	True if the checkout is planned to auto renew
auto_renew_error	auto_renew_error	Auto renewal error
timestamp	timestamp	Date and time of last change of the checkout
issuedate	checkout_date	Date the item was checked out or issued
onsite_checkout	onsite_checkout	In-house use flag
note	note	Checkout note
notedate	note_date	Datetime when note was created

Patron's checkouts

Routes and actions

Description	Action	Proposed path	Bug report
Fetch patron's checkouts	GET	/patrons/{patron_id}/checkouts	Bug 22613

Object definition

Same as above

Checkout renewability

Routes and actions

Description	Action	Proposed path
Find out checkout renewability	GET	/checkouts/{checkout_id}/allows_renewal

Response definition

200 OK and object representing the state, if renewable, in which conditions, how many times is it possible....

Key	Description
allows_renewal	Boolean, true if renewable, false if not renewable
max_renewals	Maximum number of possible renewals
current_renewals	Current used renewals
error	If not renewable, the reason why

Update - Circulation history aka old checkouts

This update was voted on Development_IRC_meeting_10_April_2019

By default, the checkouts endpoint return only current checkouts. Historical checkout could be get by adding additional parameter:

/checkouts?checked_in=1

/patrons/{patron_id}/checkouts?checked_in=1

Comments

Comments from Ere Maijala:

• While fetching the information about the checkout itself is a good start, often some more information is needed, and if it means that several requests need to be made, things get slow pretty quickly. So I'd suggest adding an expanded version of the response with at least the following extra information. This is based on my experiences with integrating several different ILS's (including Koha with our own REST API version) with our VuFind-based discovery interface.

1. Renewability
2. Maximum number of renewals
3. Basic information about the biblio and item (biblio.biblionumber, biblio.title, items.barcode, items.enumchron)

• When there are a lot of loans, supporting server-side paging and sorting can make a huge difference (especially with the expanded response). This could be accomplished with the addition of offset, limit and sort parameters.
• 403 is valid response code if you try to renew a non-renewable loan, but error codes should not be used to indicate a status. So the renewability check should rather return 200 and an actual response telling if renewal is possible.
  
  

Answers on Ere from Josef Moravec:

• Getting also some related information is good idea and we would like to add it in the future, but first, we would like to have at least something functional, end then extend it.
• Server side paging and sorting is implemented in our API, it uses order_by, page and per_page params
• Status of renewability return is changed, it returns an object with some additional informations

Comments from --Kfischer 11:39, 27 October 2018 (EDT)

• return_date: should be checkin_date. But maybe it would make sense to leave that out? It's only in the table as it has to have the same structure as old_issues and is not relevant for checkouts.
• Maybe instead of renewability... loanability... we should do something like: allows_renewal, allows_checkout ... and it would be more clear.

--Kfischer 11:42, 27 February 2019 (EST) Looking again before the meeting today:

• checked_out_date => checkout_date ?

Answer on Katrin from Josef Moravec

• return_date is now checkin_date and issuedate is checkout_date
• according to to endpoint name: I changed it now to allows_renewal, we could discuss it more on meeting