From 1f98d27e2587de14ebd9fb441ac61dc134b29f55 Mon Sep 17 00:00:00 2001
From: Tomas Cohen Arazi <tomascohen@theke.io>
Date: Thu, 24 Jan 2019 14:48:26 -0300
Subject: [PATCH] Bug 20006: Spec changes

This patch makes the spec match the voted RFC.

Signed-off-by: Josef Moravec <josef.moravec@gmail.com>
---
 api/v1/swagger/definitions/hold.json |  73 ++++++++++++------------
 api/v1/swagger/parameters.json       |   4 +-
 api/v1/swagger/parameters/hold.json  |   4 +-
 api/v1/swagger/paths.json            |   4 +-
 api/v1/swagger/paths/holds.json      | 104 ++++++++++++++++-------------------
 api/v1/swagger/x-primitives.json     |  12 +---
 6 files changed, 92 insertions(+), 109 deletions(-)

diff --git a/api/v1/swagger/definitions/hold.json b/api/v1/swagger/definitions/hold.json
index 626910beb7..df8289823b 100644
--- a/api/v1/swagger/definitions/hold.json
+++ b/api/v1/swagger/definitions/hold.json
@@ -1,76 +1,77 @@
 {
   "type": "object",
   "properties": {
-    "reserve_id": {
-      "$ref": "../x-primitives.json#/reserve_id"
+    "hold_id": {
+      "type": "integer",
+      "description": "Internal hold identifier"
     },
-    "borrowernumber": {
+    "patron_id": {
       "type": "integer",
       "description": "Internal patron identifier"
     },
-    "reservedate": {
-      "type": ["string", "null"],
-      "description": "the date the hold was placed"
-    },
-    "biblionumber": {
-      "$ref": "../x-primitives.json#/biblionumber"
-    },
-    "branchcode": {
+    "hold_date": {
       "type": ["string", "null"],
-      "description": "code of patron's home branch"
+      "format": "date",
+      "description": "The date the hold was placed"
     },
-    "notificationdate": {
-      "type": ["string", "null"],
-      "description": "currently unused"
+    "biblio_id": {
+      "type": "integer",
+      "description": "Internal biblio identifier"
     },
-    "reminderdate": {
+    "pickup_library_id": {
       "type": ["string", "null"],
-      "description": "currently unused"
+      "description": "Internal library identifier for the pickup library"
     },
-    "cancellationdate": {
+    "cancelation_date": {
       "type": ["string", "null"],
-      "description": "the date the hold was cancelled"
+      "format": "date",
+      "description": "The date the hold was cancelled"
     },
-    "reservenotes": {
+    "notes": {
       "type": ["string", "null"],
-      "description": "notes related to this hold"
+      "description": "Notes related to this hold"
     },
     "priority": {
       "type": ["integer", "null"],
-      "description": "where in the queue the patron sits"
+      "description": "Where in the queue the patron sits"
     },
-    "found": {
+    "status": {
       "type": ["string", "null"],
-      "description": "a one letter code defining what the status of the hold is after it has been confirmed"
+      "description": "A one letter code defining what the status of the hold is after it has been confirmed"
     },
     "timestamp": {
-      "type": ["string", "null"],
-      "description": "date and time the hold was last updated"
+      "type": "string",
+      "format": "date-time",
+      "description": "Timestamp for the latest hold update"
     },
-    "itemnumber": {
-      "$ref": "../x-primitives.json#/itemnumber"
+    "item_id": {
+      "type": ["string", "null"],
+      "description": "Internal item identifier"
     },
-    "waitingdate": {
+    "waiting_date": {
       "type": ["string", "null"],
-      "description": "the date the item was marked as waiting for the patron at the library"
+      "format": "date",
+      "description": "The date the item was marked as waiting for the patron at the library"
     },
-    "expirationdate": {
+    "expiration_date": {
       "type": ["string", "null"],
-      "description": "the date the hold expires"
+      "format": "date",
+      "description": "The date the hold expires"
     },
-    "lowestPriority": {
+    "lowest_priority": {
       "type": "boolean",
       "description": "Controls if the hold is given the lowest priority on the queue"
     },
-    "suspend": {
+    "suspended": {
       "type": "boolean",
       "description": "Controls if the hold is suspended"
     },
-    "suspend_until": {
+    "suspended_until": {
       "type": ["string", "null"],
+      "format": "date-time",
       "description": "Date until which the hold has been suspended"
     },
-    "itemtype": {
+    "item_type": {
       "type": ["string", "null"],
       "description": "If record level hold, the optional itemtype of the item the patron is requesting"
     }
diff --git a/api/v1/swagger/parameters.json b/api/v1/swagger/parameters.json
index d951cf7d99..8242ffa774 100644
--- a/api/v1/swagger/parameters.json
+++ b/api/v1/swagger/parameters.json
@@ -8,8 +8,8 @@
   "city_id_pp": {
     "$ref": "parameters/city.json#/city_id_pp"
   },
-  "holdIdPathParam": {
-    "$ref": "parameters/hold.json#/holdIdPathParam"
+  "hold_id_pp": {
+    "$ref": "parameters/hold.json#/hold_id_pp"
   },
   "vendoridPathParam": {
     "$ref": "parameters/vendor.json#/vendoridPathParam"
diff --git a/api/v1/swagger/parameters/hold.json b/api/v1/swagger/parameters/hold.json
index d8177e1e4a..7e71cbb784 100644
--- a/api/v1/swagger/parameters/hold.json
+++ b/api/v1/swagger/parameters/hold.json
@@ -1,6 +1,6 @@
 {
-  "holdIdPathParam": {
-    "name": "reserve_id",
+  "hold_id_pp": {
+    "name": "hold_id",
     "in": "path",
     "description": "Internal hold identifier",
     "required": true,
diff --git a/api/v1/swagger/paths.json b/api/v1/swagger/paths.json
index c8870db2a1..2a1d59d232 100644
--- a/api/v1/swagger/paths.json
+++ b/api/v1/swagger/paths.json
@@ -17,8 +17,8 @@
   "/holds": {
     "$ref": "paths/holds.json#/~1holds"
   },
-  "/holds/{reserve_id}": {
-    "$ref": "paths/holds.json#/~1holds~1{reserve_id}"
+  "/holds/{hold_id}": {
+    "$ref": "paths/holds.json#/~1holds~1{hold_id}"
   },
   "/patrons": {
     "$ref": "paths/patrons.json#/~1patrons"
diff --git a/api/v1/swagger/paths/holds.json b/api/v1/swagger/paths/holds.json
index 453533a5e5..c4139106e5 100644
--- a/api/v1/swagger/paths/holds.json
+++ b/api/v1/swagger/paths/holds.json
@@ -6,67 +6,57 @@
       "tags": ["patrons", "holds"],
       "parameters": [
         {
-          "name": "reserve_id",
+          "name": "hold_id",
           "in": "query",
           "description": "Internal reserve identifier",
           "type": "integer"
         },
         {
-          "name": "borrowernumber",
+          "name": "patron_id",
           "in": "query",
           "description": "Internal patron identifier",
           "type": "integer"
         },
         {
-          "name": "reservedate",
+          "name": "hold_date",
           "in": "query",
-          "description": "Reserve date",
-          "type": "string"
+          "description": "Hold",
+          "type": "string",
+          "format": "date"
         },
         {
-          "name": "biblionumber",
+          "name": "biblio_id",
           "in": "query",
           "description": "Internal biblio identifier",
           "type": "integer"
         },
         {
-          "name": "branchcode",
-          "in": "query",
-          "description": "Branch code",
-          "type": "string"
-        },
-        {
-          "name": "notificationdate",
+          "name": "pickup_library_id",
           "in": "query",
-          "description": "Notification date",
+          "description": "Internal library identifier for the pickup library",
           "type": "string"
         },
         {
-          "name": "reminderdate",
+          "name": "cancelation_date",
           "in": "query",
-          "description": "Reminder date",
-          "type": "string"
-        },
-        {
-          "name": "cancellationdate",
-          "in": "query",
-          "description": "Cancellation date",
-          "type": "string"
+          "description": "The date the hold was cancelled",
+          "type": "string",
+          "format": "date"
         },
         {
-          "name": "reservenotes",
+          "name": "notes",
           "in": "query",
-          "description": "Reserve notes",
+          "description": "Notes related to this hold",
           "type": "string"
         },
         {
           "name": "priority",
           "in": "query",
-          "description": "Priority",
+          "description": "Where in the queue the patron sits",
           "type": "integer"
         },
         {
-          "name": "found",
+          "name": "status",
           "in": "query",
           "description": "Found status",
           "type": "string"
@@ -78,37 +68,37 @@
           "type": "string"
         },
         {
-          "name": "itemnumber",
+          "name": "item_id",
           "in": "query",
           "description": "Internal item identifier",
           "type": "integer"
         },
         {
-          "name": "waitingdate",
+          "name": "waiting_date",
           "in": "query",
           "description": "Date the item was marked as waiting for the patron",
           "type": "string"
         },
         {
-          "name": "expirationdate",
+          "name": "expiration_date",
           "in": "query",
           "description": "Date the hold expires",
           "type": "string"
         },
         {
-          "name": "lowestPriority",
+          "name": "lowest_priority",
           "in": "query",
           "description": "Lowest priority",
-          "type": "integer"
+          "type": "boolean"
         },
         {
-          "name": "suspend",
+          "name": "suspended",
           "in": "query",
           "description": "Suspended",
-          "type": "integer"
+          "type": "boolean"
         },
         {
-          "name": "suspend_until",
+          "name": "suspended_until",
           "in": "query",
           "description": "Suspended until",
           "type": "string"
@@ -154,8 +144,6 @@
         }
       },
       "x-koha-authorization": {
-        "allow-owner": true,
-        "allow-guarantor": true,
         "permissions": {
           "borrowers": "edit_borrowers"
         }
@@ -173,32 +161,37 @@
           "schema": {
             "type": "object",
             "properties": {
-              "borrowernumber": {
+              "patron_id": {
                 "description": "Internal patron identifier",
                 "type": "integer"
               },
-              "biblionumber": {
-                "description": "Biblio internal identifier",
-                "type": "integer"
+              "biblio_id": {
+                "description": "Internal biblio identifier",
+                "type": [ "integer", "null" ]
               },
-              "itemnumber": {
-                "description": "Item internal identifier",
-                "type": "integer"
+              "item_id": {
+                "description": "Internal item identifier",
+                "type": [ "integer", "null" ]
               },
-              "branchcode": {
-                "description": "Pickup location",
+              "pickup_library_id": {
+                "description": "Internal library identifier for the pickup library",
                 "type": "string"
               },
-              "expirationdate": {
+              "expiration_date": {
                 "description": "Hold end date",
-                "type": "string",
+                "type": ["string", "null"],
                 "format": "date"
               },
-              "itemtype": {
+              "notes": {
+                "description": "Notes related to this hold",
+                "type": [ "string", "null" ]
+              },
+              "item_type": {
                 "description": "Limit hold on one itemtype (ignored for item-level holds)",
-                "type": "string"
+                "type": [ "string", "null" ]
               }
-            }
+            },
+            "required": [ "patron_id", "pickup_library_id" ]
           }
         }
       ],
@@ -249,20 +242,19 @@
         }
       },
       "x-koha-authorization": {
-        "allow-owner": true,
         "permissions": {
           "reserveforothers": "1"
         }
       }
     }
   },
-  "/holds/{reserve_id}": {
+  "/holds/{hold_id}": {
     "put": {
       "x-mojo-to": "Hold#edit",
       "operationId": "editHold",
       "tags": ["holds"],
       "parameters": [{
-          "$ref": "../parameters.json#/holdIdPathParam"
+          "$ref": "../parameters.json#/hold_id_pp"
         }, {
           "name": "body",
           "in": "body",
@@ -336,8 +328,6 @@
         }
       },
       "x-koha-authorization": {
-        "allow-owner": true,
-        "allow-guarantor": true,
         "permissions": {
           "reserveforothers": "1"
         }
@@ -348,7 +338,7 @@
       "operationId": "deleteHold",
       "tags": ["holds"],
       "parameters": [{
-          "$ref": "../parameters.json#/holdIdPathParam"
+          "$ref": "../parameters.json#/hold_id_pp"
         }
       ],
       "produces": ["application/json"],
diff --git a/api/v1/swagger/x-primitives.json b/api/v1/swagger/x-primitives.json
index 0266297cee..1a9105eefb 100644
--- a/api/v1/swagger/x-primitives.json
+++ b/api/v1/swagger/x-primitives.json
@@ -1,7 +1,7 @@
 {
-  "biblionumber": {
+  "biblio_id": {
     "type": "integer",
-    "description": "internally assigned biblio identifier"
+    "description": "Internal biblio identifier"
   },
   "patron_id": {
     "type": "integer",
@@ -24,18 +24,10 @@
     "type": ["string", "null"],
     "description": "patron's first name"
   },
-  "itemnumber": {
-    "type": ["integer", "null"],
-    "description": "internally assigned item identifier"
-  },
   "phone": {
     "type": ["string", "null"],
     "description": "primary phone number for patron's primary address"
   },
-  "reserve_id": {
-    "type": "integer",
-    "description": "Internal hold identifier"
-  },
   "surname": {
     "type": "string",
     "description": "patron's last name"
-- 
2.11.0