From b212979c6ee659cecc77cb49d324660723343223 Mon Sep 17 00:00:00 2001 From: Lari Taskula Date: Tue, 22 Nov 2016 16:41:09 +0200 Subject: [PATCH] Bug 16826: Availability Swagger definitions GET /availability/biblio/hold GET /availability/biblio/search GET /availability/item/checkout GET /availability/item/hold GET /availability/item/search --- api/v1/swagger/definitions.json | 9 + api/v1/swagger/definitions/availability.json | 18 + .../swagger/definitions/availability/biblio.json | 19 + api/v1/swagger/definitions/availability/item.json | 52 +++ .../swagger/definitions/availability/reason.json | 404 +++++++++++++++++++++ api/v1/swagger/parameters.json | 9 + api/v1/swagger/parameters/biblio.json | 12 + api/v1/swagger/parameters/item.json | 10 + api/v1/swagger/parameters/library.json | 8 + api/v1/swagger/paths.json | 15 + api/v1/swagger/paths/availability.json | 203 +++++++++++ api/v1/swagger/x-primitives.json | 4 + 12 files changed, 763 insertions(+) create mode 100644 api/v1/swagger/definitions/availability.json create mode 100644 api/v1/swagger/definitions/availability/biblio.json create mode 100644 api/v1/swagger/definitions/availability/item.json create mode 100644 api/v1/swagger/definitions/availability/reason.json create mode 100644 api/v1/swagger/parameters/biblio.json create mode 100644 api/v1/swagger/parameters/library.json create mode 100644 api/v1/swagger/paths/availability.json diff --git a/api/v1/swagger/definitions.json b/api/v1/swagger/definitions.json index a92fe4b..f213251 100644 --- a/api/v1/swagger/definitions.json +++ b/api/v1/swagger/definitions.json @@ -1,4 +1,13 @@ { + "availability": { + "$ref": "definitions/availability.json" + }, + "availability/biblio": { + "$ref": "definitions/availability/biblio.json" + }, + "availability/item": { + "$ref": "definitions/availability/item.json" + }, "city": { "$ref": "definitions/city.json" }, diff --git a/api/v1/swagger/definitions/availability.json b/api/v1/swagger/definitions/availability.json new file mode 100644 index 0000000..d7e6095 --- /dev/null +++ b/api/v1/swagger/definitions/availability.json @@ -0,0 +1,18 @@ +{ + "type": "object", + "properties": { + "available": { + "type": "boolean", + "description": "Availability status" + }, + "confirmations": { + "$ref": "./availability/reason.json" + }, + "notes": { + "$ref": "./availability/reason.json" + }, + "unavailabilities": { + "$ref": "./availability/reason.json" + } + } +} diff --git a/api/v1/swagger/definitions/availability/biblio.json b/api/v1/swagger/definitions/availability/biblio.json new file mode 100644 index 0000000..d589092 --- /dev/null +++ b/api/v1/swagger/definitions/availability/biblio.json @@ -0,0 +1,19 @@ +{ + "type": "object", + "properties": { + "biblionumber": { + "type": "integer", + "description": "Internal biblio identifier" + }, + "availability": { + "$ref": "../availability.json" + }, + "item_availabilities": { + "description": "Availability of each item in this biblio", + "type": ["array", "null"], + "items": { + "$ref": "../availability/item.json" + } + } + } +} diff --git a/api/v1/swagger/definitions/availability/item.json b/api/v1/swagger/definitions/availability/item.json new file mode 100644 index 0000000..0289752 --- /dev/null +++ b/api/v1/swagger/definitions/availability/item.json @@ -0,0 +1,52 @@ +{ + "type": "object", + "properties": { + "availability": { + "$ref": "../availability.json" + }, + "barcode": { + "type": ["string", "null"], + "description": "item barcode" + }, + "biblioitemnumber": { + "type": "integer", + "description": "internally assigned biblio item identifier" + }, + "biblionumber": { + "type": "integer", + "description": "internally assigned biblio identifier" + }, + "enumchron": { + "type": ["string", "null"], + "description": "serial enumeration/chronology for the item" + }, + "holdQueueLength": { + "type": ["integer", "null"], + "description": "number of holdings placed on title/item" + }, + "holdingbranch": { + "type": ["string", "null"], + "description": "library that is currently in possession item" + }, + "homebranch": { + "type": ["string", "null"], + "description": "library that owns this item" + }, + "itemcallnumber": { + "type": ["string", "null"], + "description": "call number for this item" + }, + "itemnotes": { + "type": ["string", "null"], + "description": "public notes on this item" + }, + "itemnumber": { + "type": "integer", + "description": "internally assigned item identifier" + }, + "location": { + "type": ["string", "null"], + "description": "authorized value for the shelving location for this item" + } + } +} diff --git a/api/v1/swagger/definitions/availability/reason.json b/api/v1/swagger/definitions/availability/reason.json new file mode 100644 index 0000000..04df081 --- /dev/null +++ b/api/v1/swagger/definitions/availability/reason.json @@ -0,0 +1,404 @@ +{ + "description": "An object that contains either none or multiple reasons defined in this object's specification.", + "type": "object", + "properties": { + "Biblio::CheckedOut": { + "description": "Patron has already checked out an item from this biblio. A confirmation may be required.", + "type": "object", + "properties": { + "biblionumber": { + "$ref": "../../x-primitives.json#/biblionumber" + } + } + }, + "Biblio::NoAvailableItems": { + "description": "This biblio has no available items.", + "type": "object", + "properties": {} + }, + "Checkout::DueDateBeforeNow": { + "description": "Given due date is in the past.", + "type": "object", + "properties": { + "duedate": { + "type": ["string", "null"], + "format": "date-time" + }, + "now": { + "type": ["string", "null"], + "format": "date-time" + } + } + }, + "Checkout::Fee": { + "description": "Checkout fee will apply.", + "type": "object", + "properties": { + "amount": { + "type": ["number", "null"], + "description": "Amount of rental charge." + } + } + }, + "Checkout::InvalidDueDate": { + "description": "Given due date is invalid.", + "type": "object", + "properties": { + "duedate": { + "type": ["string", "null"] + } + } + }, + "Checkout::MaximumCheckoutsReached": { + "description": "Maximum number of checkouts have been reached.", + "type": "object", + "properties": { + "max_checkouts_allowed": { + "type": ["integer", "null"], + "description": "Maximum number of checkouts allowed." + }, + "current_checkout_count": { + "type": ["integer", "null"], + "description": "Current checkout count for patron." + } + } + }, + "Checkout::MaximumOnsiteCheckoutsReached": { + "description": "Maximum number of on-site checkouts have been reached.", + "type": "object", + "properties": { + "max_onsite_checkouts": { + "type": ["integer", "null"], + "description": "Maximum number of onsite checkouts allowed." + }, + "current_onsite_checkouts": { + "type": ["integer", "null"], + "description": "Current onsite checkout count for patron." + } + } + }, + "Checkout::NoMoreRenewals": { + "description": "No more renewals allowed.", + "type": "object", + "properties": {} + }, + "Checkout::NoMoreRenewalForOnsiteCheckouts": { + "description": "No more on-site renewals allowed.", + "type": "object", + "properties": {} + }, + "Checkout::OnsiteCheckoutsDisabled": { + "description": "On-site checkouts are disabled.", + "type": "object", + "properties": {} + }, + "Checkout::Renew": { + "description": "Checkout will be renewed.", + "type": "object", + "properties": {} + }, + "Checkout::ZeroCheckoutsAllowed": { + "description": "Allowed number of checkouts is zero.", + "type": "object", + "properties": {} + }, + "Hold::ItemLevelHoldNotAllowed": { + "description": "Item-level holds are not allowed.", + "type": "object", + "properties": {} + }, + "Hold::MaximumHoldsReached": { + "description": "Maximum number of holds have been reached.", + "type": "object", + "properties": { + "max_holds_allowed": { + "type": ["integer", "null"] + }, + "current_hold_count": { + "type": ["integer", "null"] + } + } + }, + "Hold::MaximumHoldsForThisRecordReached": { + "description": "Maximum number of holds for this record have been reached.", + "type": "object", + "properties": { + "max_holds_allowed": { + "type": ["integer", "null"] + }, + "current_hold_count": { + "type": ["integer", "null"] + } + } + }, + "Hold::NotAllowedByLibrary": { + "description": "Library does not allow holds to be placed.", + "type": "object", + "properties": {} + }, + "Hold::NotAllowedFromOtherLibraries": { + "description": "Holds are not allowed from other libraries.", + "type": "object", + "properties": {} + }, + "Hold::NotAllowedInOPAC": { + "description": "Patron cannot place a hold by themselves in OPAC.", + "type": "object", + "properties": {} + }, + "Hold::OnShelfNotAllowed": { + "description": "On-shelf holds are not allowed.", + "type": "object", + "properties": {} + }, + "Hold::ZeroHoldsAllowed": { + "description": "Allowed number of holds is zero.", + "type": "object", + "properties": {} + }, + "Item::AlreadyHeldForThisPatron": { + "description": "Item is held for this patron.", + "type": "object", + "properties": {} + }, + "Item::CannotBeTransferred": { + "description": "Item cannot be transferred.", + "type": "object", + "properties": { + "from_library": { + "$ref": "../../x-primitives.json#/branchcode" + }, + "to_library": { + "$ref": "../../x-primitives.json#/branchcode" + } + } + }, + "Item::CheckedOut": { + "description": "Item is checked out to a patron.", + "type": "object", + "properties": { + "borrowernumber": { + "type": ["integer", "null"] + }, + "date_due": { + "type": ["string", "null"], + "format": "date-time" + } + } + }, + "Item::Damaged": { + "description": "Item is marked as damaged", + "type": "object", + "properties": {} + }, + "Item::FromAnotherLibrary": { + "description": "Libraries are independent and this item is from another library than current patron.", + "type": "object", + "properties": { + "itemhomebranch": { + "$ref": "../../x-primitives.json#/branchcode" + } + } + }, + "Item::Held": { + "description": "Someone has placed a hold on this item.", + "type": "object", + "properties": { + "borrowernumber": { + "$ref": "../../x-primitives.json#/borrowernumber" + }, + "status": { + "type": ["string", "null"] + }, + "hold_queue_length": { + "type": ["integer", "null"] + } + } + }, + "Item::HighHolds": { + "description": "Loan period shortened for high held item.", + "type": "object", + "properties": { + "num_holds": { + "type": ["integer", "null"] + }, + "duration": { + "type": ["string", "null"] + }, + "returndate": { + "type": ["string", "null"], + "format": "date-time" + } + } + }, + "Item::Lost": { + "description": "Item is marked as lost.", + "type": "object", + "properties": { + "code": { + "description": "Status description (e.g. Missing)", + "type": ["string", "null"] + }, + "status": { + "description": "Item's lost status number", + "type": ["integer", "null"] + } + } + }, + "Item::NotForLoan": { + "description": "Item is not for loan.", + "type": "object", + "properties": { + "status": { + "description": "Item's notforloan status number", + "type": ["integer", "null"] + }, + "code": { + "description": "Status description (e.g. Ordered)", + "type": ["string", "null"] + } + } + }, + "Item::Restricted": { + "description": "Item is restricted.", + "type": "object", + "properties": {} + }, + "Item::Transfer": { + "description": "Item is being transferred.", + "type": "object", + "properties": { + "from_library": { + "$ref": "../../x-primitives.json#/branchcode" + }, + "to_library": { + "$ref": "../../x-primitives.json#/branchcode" + }, + "datesent": { + "description": "Start date of transfer", + "type": ["string", "null"], + "format": "date-time" + } + } + }, + "Item::UnknownBarcode": { + "description": "This item has either an unknown barcode or no barcode at all.", + "type": "object", + "properties": { + "barcode": { + "type": ["string", "null"] + } + } + }, + "Item::Withdrawn": { + "description": "Item is withdrawn.", + "type": "object", + "properties": {} + }, + "ItemType::NotForLoan": { + "description": "Item type is not for loan.", + "type": "object", + "properties": { + "status": { + "description": "Item's notforloan status number", + "type": ["integer", "null"] + }, + "code": { + "description": "Status description (e.g. Ordered)", + "type": ["string", "null"] + }, + "itemtype": { + "description": "Item type", + "type": ["string", "null"] + } + } + }, + "Patron::AgeRestricted": { + "description": "An age restriction applies for this patron.", + "type": "object", + "properties": { + "age_restriction": { + "type": ["string", "null"], + "description": "Age restriction, e.g. PEGI 16" + } + } + }, + "Patron::CardExpired": { + "description": "Patron's card has been expired.", + "type": "object", + "properties": { + "expiration_date": { + "type": ["string", "null"], + "format": "date" + } + } + }, + "Patron::CardLost": { + "description": "Patron's card has been marked as lost.", + "type": "object", + "properties": {} + }, + "Patron::Debarred": { + "description": "Patron is debarred.", + "type": "object", + "properties": { + "expiration_date": { + "type": ["string", "null"], + "format": "date" + }, + "comment": { + "type": ["string", "null"] + } + } + }, + "Patron::DebarredOverdue": { + "description": "Patron has overdues and is debarred.", + "type": "object", + "properties": { + "number_of_overdues": { + "type": ["integer", "null"] + } + } + }, + "Patron::Debt": { + "description": "Patron's debts exceed maximum allowed amount.", + "type": "object", + "properties": { + "max_outstanding":{ + "type": ["number", "null"] + }, + "current_outstanding": { + "type": ["number", "null"] + } + } + }, + "Patron::DebtGuarantees": { + "description": "Patron's guarantees' debts exceed maximum allowed amount.", + "type": "object", + "properties": { + "max_outstanding":{ + "type": ["number", "null"] + }, + "current_outstanding": { + "type": ["number", "null"] + } + } + }, + "Patron::FromAnotherLibrary": { + "description": "Libraries are independent and patron is from another library than current logged in user.", + "type": "object", + "properties": { + "patron_branch": { + "$ref": "../../x-primitives.json#/branchcode" + }, + "current_branch": { + "$ref": "../../x-primitives.json#/branchcode" + } + } + }, + "Patron::GoneNoAddress": { + "type": "object", + "properties": {} + } + } +} diff --git a/api/v1/swagger/parameters.json b/api/v1/swagger/parameters.json index f11031f..ed62fef 100644 --- a/api/v1/swagger/parameters.json +++ b/api/v1/swagger/parameters.json @@ -1,10 +1,16 @@ { + "biblionumbersQueryParam": { + "$ref": "parameters/biblio.json#/biblionumbersQueryParam" + }, "borrowernumberPathParam": { "$ref": "parameters/patron.json#/borrowernumberPathParam" }, "borrowernumberQueryParam": { "$ref": "parameters/patron.json#/borrowernumberQueryParam" }, + "branchcodeQueryParam": { + "$ref": "parameters/library.json#/branchcodeQueryParam" + }, "cityidPathParam": { "$ref": "parameters/city.json#/cityidPathParam" }, @@ -13,5 +19,8 @@ }, "itemnumberPathParam": { "$ref": "parameters/item.json#/itemnumberPathParam" + }, + "itemnumbersQueryParam": { + "$ref": "parameters/item.json#/itemnumbersQueryParam" } } diff --git a/api/v1/swagger/parameters/biblio.json b/api/v1/swagger/parameters/biblio.json new file mode 100644 index 0000000..b5d9534 --- /dev/null +++ b/api/v1/swagger/parameters/biblio.json @@ -0,0 +1,12 @@ +{ + "biblionumbersQueryParam": { + "name": "biblionumber", + "in": "query", + "description": "Internal biblios identifier", + "type": "array", + "items": { + "type": "integer" + }, + "collectionFormat": "ssv" + } +} diff --git a/api/v1/swagger/parameters/item.json b/api/v1/swagger/parameters/item.json index c215adb..409be6c 100644 --- a/api/v1/swagger/parameters/item.json +++ b/api/v1/swagger/parameters/item.json @@ -5,5 +5,15 @@ "description": "Internal item identifier", "required": true, "type": "integer" + }, + "itemnumbersQueryParam": { + "name": "itemnumber", + "in": "query", + "description": "Internal items identifier", + "type": "array", + "items": { + "type": "integer" + }, + "collectionFormat": "ssv" } } diff --git a/api/v1/swagger/parameters/library.json b/api/v1/swagger/parameters/library.json new file mode 100644 index 0000000..7bc63b4 --- /dev/null +++ b/api/v1/swagger/parameters/library.json @@ -0,0 +1,8 @@ +{ + "branchcodeQueryParam": { + "name": "branchcode", + "in": "query", + "description": "Branch identifier code", + "type": "string" + } +} diff --git a/api/v1/swagger/paths.json b/api/v1/swagger/paths.json index 73729c1..2bc21bf 100644 --- a/api/v1/swagger/paths.json +++ b/api/v1/swagger/paths.json @@ -1,4 +1,19 @@ { + "/availability/biblio/hold": { + "$ref": "paths/availability.json#/~1availability~1biblio~1hold" + }, + "/availability/biblio/search": { + "$ref": "paths/availability.json#/~1availability~1biblio~1search" + }, + "/availability/item/checkout": { + "$ref": "paths/availability.json#/~1availability~1item~1checkout" + }, + "/availability/item/hold": { + "$ref": "paths/availability.json#/~1availability~1item~1hold" + }, + "/availability/item/search": { + "$ref": "paths/availability.json#/~1availability~1item~1search" + }, "/cities": { "$ref": "paths/cities.json#/~1cities" }, diff --git a/api/v1/swagger/paths/availability.json b/api/v1/swagger/paths/availability.json new file mode 100644 index 0000000..d7ab4c6 --- /dev/null +++ b/api/v1/swagger/paths/availability.json @@ -0,0 +1,203 @@ +{ + "/availability/biblio/hold": { + "get": { + "operationId": "holdBiblioAvailability", + "tags": ["items", "availability"], + "parameters": [ + { "$ref": "../parameters.json#/biblionumbersQueryParam" }, + { "$ref": "../parameters.json#/borrowernumberQueryParam" }, + { "$ref": "../parameters.json#/branchcodeQueryParam"} + ], + "consumes": ["application/json"], + "produces": ["application/json"], + "responses": { + "200": { + "description": "Hold availability information for items of biblio.", + "schema": { + "type": "array", + "items": { "$ref": "../definitions.json#/availability~1biblio" } + } + }, + "400": { + "description": "Missing or invalid parameters", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "401": { + "description": "Authentication required", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "500": { + "description": "Internal server error", + "schema": { + "$ref": "../definitions.json#/error" + } + } + } + } + }, + "/availability/biblio/search": { + "get": { + "operationId": "searchBiblioAvailability", + "tags": ["items", "availability"], + "parameters": [ + { "$ref": "../parameters.json#/biblionumbersQueryParam" } + ], + "consumes": ["application/json"], + "produces": ["application/json"], + "responses": { + "200": { + "description": "Availability information in search context for items of biblio.", + "schema": { + "type": "array", + "items": { "$ref": "../definitions.json#/availability~1biblio" } + } + }, + "400": { + "description": "Missing or invalid parameters", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "500": { + "description": "Internal server error", + "schema": { + "$ref": "../definitions.json#/error" + } + } + } + } + }, + "/availability/item/checkout": { + "get": { + "operationId": "checkoutItemAvailability", + "tags": ["items", "availability"], + "parameters": [ + { "$ref": "../parameters.json#/itemnumbersQueryParam" }, + { "$ref": "../parameters.json#/borrowernumberQueryParam" } + ], + "consumes": ["application/json"], + "produces": ["application/json"], + "responses": { + "200": { + "description": "Checkout availability information for specific item(s).", + "schema": { + "type": "array", + "items": { "$ref": "../definitions.json#/availability~1item" } + } + }, + "400": { + "description": "Missing or invalid parameters", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "401": { + "description": "Authentication required", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "500": { + "description": "Internal server error", + "schema": { + "$ref": "../definitions.json#/error" + } + } + } + } + }, + "/availability/item/hold": { + "get": { + "operationId": "holdItemAvailability", + "tags": ["items", "availability"], + "parameters": [ + { "$ref": "../parameters.json#/itemnumbersQueryParam" }, + { "$ref": "../parameters.json#/borrowernumberQueryParam" }, + { "$ref": "../parameters.json#/branchcodeQueryParam"} + ], + "consumes": ["application/json"], + "produces": ["application/json"], + "responses": { + "200": { + "description": "Hold availability information for specific item(s).", + "schema": { + "type": "array", + "items": { "$ref": "../definitions.json#/availability~1item" } + } + }, + "400": { + "description": "Missing or invalid parameters", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "401": { + "description": "Authentication required", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "403": { + "description": "Forbidden", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "500": { + "description": "Internal server error", + "schema": { + "$ref": "../definitions.json#/error" + } + } + } + } + }, + "/availability/item/search": { + "get": { + "operationId": "searchItemAvailability", + "tags": ["items", "availability"], + "parameters": [ + { "$ref": "../parameters.json#/itemnumbersQueryParam" } + ], + "consumes": ["application/json"], + "produces": ["application/json"], + "responses": { + "200": { + "description": "Availability information in search context for specific item(s).", + "schema": { + "type": "array", + "items": { "$ref": "../definitions.json#/availability~1item" } + } + }, + "400": { + "description": "Missing or invalid parameters", + "schema": { + "$ref": "../definitions.json#/error" + } + }, + "500": { + "description": "Internal server error", + "schema": { + "$ref": "../definitions.json#/error" + } + } + } + } + } +} diff --git a/api/v1/swagger/x-primitives.json b/api/v1/swagger/x-primitives.json index ae4e739..7337889 100644 --- a/api/v1/swagger/x-primitives.json +++ b/api/v1/swagger/x-primitives.json @@ -7,6 +7,10 @@ "type": "integer", "description": "internally assigned user identifier" }, + "branchcode": { + "type": "string", + "description": "a unique key assigned to each branch" + }, "cardnumber": { "type": ["string", "null"], "description": "library assigned user identifier" -- 1.9.1