Bug 13903: Add API routes to list, create, update, delete reserves
[koha.git] / api / v1 / swagger.json
1 {
2   "swagger": "2.0",
3   "info": {
4     "title": "Koha REST API",
5     "version": "1",
6     "license": {
7       "name": "GPL v3",
8       "url": "http://www.gnu.org/licenses/gpl.txt"
9     },
10     "contact": {
11       "name": "Koha Team",
12       "url": "http://koha-community.org/"
13     }
14   },
15   "basePath": "/api/v1",
16   "paths": {
17     "/patrons": {
18       "get": {
19         "operationId": "listPatrons",
20         "tags": ["patrons"],
21         "produces": [
22           "application/json"
23         ],
24         "responses": {
25           "200": {
26             "description": "A list of patrons",
27             "schema": {
28               "type": "array",
29               "items": {
30                 "$ref": "#/definitions/patron"
31               }
32             }
33           },
34           "403": {
35             "description": "Access forbidden",
36             "schema": {
37               "$ref": "#/definitions/error"
38             }
39           }
40         }
41       }
42     },
43     "/patrons/{borrowernumber}": {
44       "get": {
45         "operationId": "getPatron",
46         "tags": ["patrons"],
47         "parameters": [
48           {
49             "$ref": "#/parameters/borrowernumberPathParam"
50           }
51         ],
52         "produces": [
53           "application/json"
54         ],
55         "responses": {
56           "200": {
57             "description": "A patron",
58             "schema": {
59               "$ref": "#/definitions/patron"
60             }
61           },
62           "403": {
63             "description": "Access forbidden",
64             "schema": {
65               "$ref": "#/definitions/error"
66             }
67           },
68           "404": {
69             "description": "Patron not found",
70             "schema": {
71               "$ref": "#/definitions/error"
72             }
73           }
74         }
75       }
76     },
77     "/reserves": {
78       "get": {
79         "operationId": "listReserves",
80         "tags": ["borrowers", "reserves"],
81         "parameters": [
82           {
83             "name": "borrowernumber",
84             "in": "query",
85             "description": "Internal borrower identifier",
86             "required": true,
87             "type": "integer"
88           }
89         ],
90         "produces": ["application/json"],
91         "responses": {
92           "200": {
93             "description": "A list of reserves",
94             "schema": { "$ref": "#/definitions/reserves" }
95           },
96           "404": {
97             "description": "Borrower not found",
98             "schema": { "$ref": "#/definitions/error" }
99           }
100         }
101       },
102       "post": {
103         "operationId": "addReserve",
104         "tags": ["borrowers", "reserves"],
105         "parameters": [
106           {
107             "name": "body",
108             "in": "body",
109             "description": "A JSON object containing informations about the new reserve",
110             "required": true,
111             "schema": {
112               "type": "object",
113               "properties": {
114                 "borrowernumber": {
115                   "description": "Borrower internal identifier",
116                   "type": "integer"
117                 },
118                 "biblionumber": {
119                   "description": "Biblio internal identifier",
120                   "type": "integer"
121                 },
122                 "itemnumber": {
123                   "description": "Item internal identifier",
124                   "type": "integer"
125                 },
126                 "branchcode": {
127                   "description": "Pickup location",
128                   "type": "string"
129                 },
130                 "expirationdate": {
131                   "description": "Reserve end date",
132                   "type": "string",
133                   "format": "date"
134                 }
135               }
136             }
137           }
138         ],
139         "consumes": ["application/json"],
140         "produces": ["application/json"],
141         "responses": {
142           "201": {
143             "description": "Created reserve",
144             "schema": { "$ref": "#/definitions/reserve" }
145           },
146           "400": {
147             "description": "Missing or wrong parameters",
148             "schema": { "$ref": "#/definitions/error" }
149           },
150           "403": {
151             "description": "Reserve not allowed",
152             "schema": { "$ref": "#/definitions/error" }
153           },
154           "404": {
155             "description": "Borrower not found",
156             "schema": { "$ref": "#/definitions/error" }
157           },
158           "500": {
159             "description": "Internal error",
160             "schema": { "$ref": "#/definitions/error" }
161           }
162         }
163       }
164     },
165     "/reserves/{reserve_id}": {
166       "put": {
167         "operationId": "editReserve",
168         "tags": ["reserves"],
169         "parameters": [
170           { "$ref": "#/parameters/reserveIdPathParam" },
171           {
172             "name": "body",
173             "in": "body",
174             "description": "A JSON object containing fields to modify",
175             "required": true,
176             "schema": {
177               "type": "object",
178               "properties": {
179                 "priority": {
180                   "description": "Position in waiting queue",
181                   "type": "integer",
182                   "minimum": 1
183                 },
184                 "branchcode": {
185                   "description": "Pickup location",
186                   "type": "string"
187                 },
188                 "suspend_until": {
189                   "description": "Suspend until",
190                   "type": "string",
191                   "format": "date"
192                 }
193               }
194             }
195           }
196         ],
197         "consumes": ["application/json"],
198         "produces": ["application/json"],
199         "responses": {
200           "200": {
201             "description": "Updated reserve",
202             "schema": { "$ref": "#/definitions/reserve" }
203           },
204           "400": {
205             "description": "Missing or wrong parameters",
206             "schema": { "$ref": "#/definitions/error" }
207           },
208           "404": {
209             "description": "Reserve not found",
210             "schema": { "$ref": "#/definitions/error" }
211           }
212         }
213       },
214       "delete": {
215         "operationId": "deleteReserve",
216         "tags": ["reserves"],
217         "parameters": [
218           { "$ref": "#/parameters/reserveIdPathParam" }
219         ],
220         "produces": ["application/json"],
221         "responses": {
222           "200": {
223             "description": "Successful deletion",
224             "schema": {
225               "type": "object"
226             }
227           },
228           "404": {
229             "description": "Reserve not found",
230             "schema": { "$ref": "#/definitions/error" }
231           }
232         }
233       }
234     }
235   },
236   "definitions": {
237     "$ref": "./definitions/index.json"
238   },
239   "parameters": {
240     "borrowernumberPathParam": {
241       "name": "borrowernumber",
242       "in": "path",
243       "description": "Internal patron identifier",
244       "required": true,
245       "type": "integer"
246     },
247     "reserveIdPathParam": {
248       "name": "reserve_id",
249       "in": "path",
250       "description": "Internal reserve identifier",
251       "required": true,
252       "type": "integer"
253     }
254   }
255 }