Checkouts endpoint RFC

From Koha Wiki
Jump to navigation Jump to search

General overview

This RFC was voted on Development_IRC_meeting_13_March_2019

This RFC proposes several endpoints:


  • /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


Routes and actions

Description Action Proposed path Implementation
List checkouts
Bug 13895
Get a single checkout
Bug 13895
Create a checkout
Bug 23336
Update a checkout
Bug 24609
Return a checkout
Find out checkout renewability
Bug 17003
Renew a checkout
Bug 13895
Renew a checkout by patron (in opac)

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
Bug 22613

Object definition

Same as above

Checkout renewability

Routes and actions

Description Action Proposed path
Find out checkout renewability

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:



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