Items endpoint RFC

Actions and routes

The following table presents the current implementation, and the proposed changes.

Description	Action	Proposed
List items	GET	/items
Add an item	POST	/items
Get an item	GET	/items/{item_id}
Overwrite an item	PUT	/items/{item_id}
Delete an item	DELETE	/items/{item_id}
Partially update an item	PATCH	/items/{item_id}

Object definition

DB schema	API	Proposed API	Description
itemnumber	item_id	item_id	Internal item identifier
biblionumber	biblio_id	biblio_id	Internal identifier for the parent bibliographic record
biblioitemnumber	REMOVED	REMOVED	No point exposing internal (useless) information
barcode	barcode	external_id	The item's barcode
dateaccessioned	acquisition_date	acquisition_date	Date the item was acquired
booksellerid	acquisition_source	acquisition_source	Information about the acquisition source (it is not really a vendor id)
homebranch	home_library	home_library_id	Internal library id for the library the item belongs to
price	purchase_price	purchase_price	Purchase price
replacementprice	replacement_price	replacement_price	Cost the library charges to replace the item (e.g. if lost)
replacementpricedate	replacement_price_date	replacement_price_date	Date the replacement price is effective from
datelastborrowed	last_checkout_date	last_checkout_date	Date the item was last checked out
datelastseen	last_seen_date	last_seen_date	Date the item barcode was last scanned
stack	REMOVED	REMOVED	Unused
notforloan	notforloan	not_for_loan_status
damaged	damaged	damaged_status
damaged_on	damaged_on	damaged_date
itemlost	itemlost	lost_status
itemlost_on	itemlost_on	lost_date
withdrawn	withdrawn	withdrawn_date
withdrawn_on	withdrawn_on	withdrawn_date
itemcallnumber	itemcallnumber	callnumber
coded_location_qualifier	coded_location_qualifier	coded_location_qualifier
issues	issues	checkouts_count
renewals	renewals	renewals_count
reserves	reserves	holds_count
restricted	restricted	restricted_status
itemnotes	itemnotes	public_notes
itemnotes_nonpublic	itemnotes_nonpublic	internal_notes
holdingbranch	holdingbranch	holding_library_id
paidfor	REMOVED	REMOVED
timestamp	timestamp	timestamp
location	location	location
permanent_location	permanent_location	permanent_location
onloan	onloan	checked_out_date
cn_source	cn_source	call_number_source
cn_sort	cn_sort	call_number_sort
ccode	ccode	collection_code
materials	materials	materials_notes
uri	uri	uri
itype	itype	item_type
more_subfields_xml	more_subfields	extended_subfields
enumchron	enumchron	serial_issue_number
copynumber	copynumber	copy_number
stocknumber	stocknumber	inventory_number
new_status	new_status	new_status

Comments

--Kfischer 11:34, 27 October 2018 (EDT) Some new comments :)

• external_id: This would work for me. Not all libraries are even using tags or labels... it's hard to find some very general term here.
• home_library_id/holding_library_id: I am not sure if holding is clear. Maybe: home_library_id and current_library_id?
• extended_subfield is an XML field, how would this look like in the API?
• serial_issue_number: This can also be a volume number or similar. Maybe serial_enumeration would be better (leaving the issue out).

--Kfischer 14:18, 26 August 2018 (EDT)

• barcode: In times of RFID, I wonder if this is not misleading Is there a better/common term that could be used instead?
• dateaccessioned: acquisition_date is better, wondering if date_added or creation_date could also be options.
• holdingbranch: holding_library to match home_library and terminology.
• notforloan: Maybe for_reference. Maybe another opinion on this one.
• itemlost, itemlost_in: lost, lost_on. We already know we are talking about items here.
• itemcallnumber: callnumber. Same.
• coded_location_qualifier: Same as with stack, we don't activley use it, but some libraries might store things in there.
• issues: checkouts or checkout_count
• reserves: Should definitely be something 'holds'. Maybe: holds_count. Might be unused Bug 12530
• itemnotes_nonpublic: internal_notes
• itemnotes: public_notes
• onloan: Maybe checked_out or even due_date?
• cn_source, cn_sort: maybe callnumber_source and callnumber_sort? Makes relation clearer.
• paidfor: Or paid_for? Is not very telling and we have argued it should be removed Bug 18818 (privacy issue)
• ccode: I think collection or collection_code would be better.
• materials: Maybe use materials_notes instead as its one of our notes fields.
• itype: Use item_type (see holds API)
• more_subfields_xml: Fixed the db column name above by adding _xml.
• copynumber: copy_number
• stocknumber: Displays as Inventory number in the GUI. Suggestion: inventory_number
• enumchron: we might be able to find something better? Description in Koha varies.