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.
#Renewability
#Maximum number of renewals
#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
Category:RFCs