Bug 16330: Add routes to add, update and delete patrons
[koha.git] / api / v1 / swagger / paths / patrons.json
1 {
2   "/patrons": {
3     "get": {
4       "x-mojo-to": "Patron#list",
5       "operationId": "listPatrons",
6       "tags": ["patrons"],
7       "produces": [
8           "application/json"
9       ],
10       "parameters": [{
11         "name": "borrowernumber",
12         "in": "query",
13         "description": "Case insensetive 'starts_with' search on borrowernumber",
14         "required": false,
15         "type": "string"
16       },
17       {
18         "name": "cardnumber",
19         "in": "query",
20         "description": "Case insensetive 'starts_with' search on cardnumber",
21         "required": false,
22         "type": "string"
23       },
24       {
25         "name": "surname",
26         "in": "query",
27         "description": "Case insensetive 'starts_with' search on surname",
28         "required": false,
29         "type": "string"
30       },
31       {
32         "name": "firstname",
33         "in": "query",
34         "description": "Case insensetive 'starts_with' search on firstname",
35         "required": false,
36         "type": "string"
37       },
38       {
39         "name": "title",
40         "in": "query",
41         "description": "Case insensetive 'starts_with' search on title",
42         "required": false,
43         "type": "string"
44       },
45       {
46         "name": "othernames",
47         "in": "query",
48         "description": "Case insensetive 'starts_with' search on othernames",
49         "required": false,
50         "type": "string"
51       },
52       {
53         "name": "initials",
54         "in": "query",
55         "description": "Case insensetive 'starts_with' search on initials",
56         "required": false,
57         "type": "string"
58       },
59       {
60         "name": "streetnumber",
61         "in": "query",
62         "description": "Case insensetive 'starts_with' search on streetnumber",
63         "required": false,
64         "type": "string"
65       },
66       {
67         "name": "streettype",
68         "in": "query",
69         "description": "Case insensetive 'starts_with' search on streettype",
70         "required": false,
71         "type": "string"
72       },
73       {
74         "name": "address",
75         "in": "query",
76         "description": "Case insensetive 'starts_with' search on address",
77         "required": false,
78         "type": "string"
79       },
80       {
81         "name": "address2",
82         "in": "query",
83         "description": "Case insensetive 'starts_with' search on address2",
84         "required": false,
85         "type": "string"
86       },
87       {
88         "name": "city",
89         "in": "query",
90         "description": "Case insensetive 'starts_with' search on city",
91         "required": false,
92         "type": "string"
93       },
94       {
95         "name": "state",
96         "in": "query",
97         "description": "Case insensetive 'starts_with' search on state",
98         "required": false,
99         "type": "string"
100       },
101       {
102         "name": "zipcode",
103         "in": "query",
104         "description": "Case insensetive 'starts_with' search on zipcode",
105         "required": false,
106         "type": "string"
107       },
108       {
109         "name": "country",
110         "in": "query",
111         "description": "Case insensetive 'starts_with' search on country",
112         "required": false,
113         "type": "string"
114       },
115       {
116         "name": "email",
117         "in": "query",
118         "description": "Case insensetive 'starts_with' search on email",
119         "required": false,
120         "type": "string"
121       },
122       {
123         "name": "phone",
124         "in": "query",
125         "description": "Case insensetive 'starts_with' search on phone",
126         "required": false,
127         "type": "string"
128       },
129       {
130         "name": "mobile",
131         "in": "query",
132         "description": "Case insensetive 'starts_with' search on mobile",
133         "required": false,
134         "type": "string"
135       },
136       {
137         "name": "fax",
138         "in": "query",
139         "description": "Case insensetive 'starts_with' search on fax",
140         "required": false,
141         "type": "string"
142       },
143       {
144         "name": "emailpro",
145         "in": "query",
146         "description": "Case insensetive 'starts_with' search on emailpro",
147         "required": false,
148         "type": "string"
149       },
150       {
151         "name": "phonepro",
152         "in": "query",
153         "description": "Case insensetive 'starts_with' search on phonepro",
154         "required": false,
155         "type": "string"
156       },
157       {
158         "name": "B_streetnumber",
159         "in": "query",
160         "description": "Case insensetive 'starts_with' search on B_streetnumber",
161         "required": false,
162         "type": "string"
163       },
164       {
165         "name": "B_streettype",
166         "in": "query",
167         "description": "Case insensetive 'starts_with' search on B_streettype",
168         "required": false,
169         "type": "string"
170       },
171       {
172         "name": "B_address",
173         "in": "query",
174         "description": "Case insensetive 'starts_with' search on B_address",
175         "required": false,
176         "type": "string"
177       },
178       {
179         "name": "B_address2",
180         "in": "query",
181         "description": "Case insensetive 'starts_with' search on B_address2",
182         "required": false,
183         "type": "string"
184       },
185       {
186         "name": "B_city",
187         "in": "query",
188         "description": "Case insensetive 'starts_with' search on B_city",
189         "required": false,
190         "type": "string"
191       },
192       {
193         "name": "B_state",
194         "in": "query",
195         "description": "Case insensetive 'starts_with' search on B_state",
196         "required": false,
197         "type": "string"
198       },
199       {
200         "name": "B_zipcode",
201         "in": "query",
202         "description": "Case insensetive 'starts_with' search on B_zipcode",
203         "required": false,
204         "type": "string"
205       },
206       {
207         "name": "B_country",
208         "in": "query",
209         "description": "Case insensetive 'starts_with' search on B_country",
210         "required": false,
211         "type": "string"
212       },
213       {
214         "name": "B_email",
215         "in": "query",
216         "description": "Case insensetive 'starts_with' search on B_email",
217         "required": false,
218         "type": "string"
219       },
220       {
221         "name": "B_phone",
222         "in": "query",
223         "description": "Case insensetive 'starts_with' search on B_phone",
224         "required": false,
225         "type": "string"
226       },
227       {
228         "name": "dateofbirth",
229         "in": "query",
230         "description": "Case insensetive 'starts_with' search on dateofbirth",
231         "required": false,
232         "type": "string"
233       },
234       {
235         "name": "branchcode",
236         "in": "query",
237         "description": "Case insensetive 'starts_with' search on branchcode",
238         "required": false,
239         "type": "string"
240       },
241       {
242         "name": "categorycode",
243         "in": "query",
244         "description": "Case insensetive 'starts_with' search on categorycode",
245         "required": false,
246         "type": "string"
247       },
248       {
249         "name": "dateenrolled",
250         "in": "query",
251         "description": "Case insensetive 'starts_with' search on dateenrolled",
252         "required": false,
253         "type": "string"
254       },
255       {
256         "name": "dateexpiry",
257         "in": "query",
258         "description": "Case insensetive 'starts_with' search on dateexpiry",
259         "required": false,
260         "type": "string"
261       },
262       {
263         "name": "gonenoaddress",
264         "in": "query",
265         "description": "Case insensetive 'starts_with' search on gonenoaddress",
266         "required": false,
267         "type": "string"
268       },
269       {
270         "name": "lost",
271         "in": "query",
272         "description": "Case insensetive 'starts_with' search on lost",
273         "required": false,
274         "type": "string"
275       },
276       {
277         "name": "debarred",
278         "in": "query",
279         "description": "Case insensetive 'starts_with' search on debarred",
280         "required": false,
281         "type": "string"
282       },
283       {
284         "name": "debarredcomment",
285         "in": "query",
286         "description": "Case insensetive 'starts_with' search on debarredcomment",
287         "required": false,
288         "type": "string"
289       },
290       {
291         "name": "contactname",
292         "in": "query",
293         "description": "Case insensetive 'starts_with' search on contactname",
294         "required": false,
295         "type": "string"
296       },
297       {
298         "name": "contactfirstname",
299         "in": "query",
300         "description": "Case insensetive 'starts_with' search on contactfirstname",
301         "required": false,
302         "type": "string"
303       },
304       {
305         "name": "contacttitle",
306         "in": "query",
307         "description": "Case insensetive 'starts_with' search on contacttitle",
308         "required": false,
309         "type": "string"
310       },
311       {
312         "name": "guarantorid",
313         "in": "query",
314         "description": "Case insensetive 'starts_with' search on guarantorid",
315         "required": false,
316         "type": "string"
317       },
318       {
319         "name": "borrowernotes",
320         "in": "query",
321         "description": "Case insensetive 'starts_with' search on borrowernotes",
322         "required": false,
323         "type": "string"
324       },
325       {
326         "name": "relationship",
327         "in": "query",
328         "description": "Case insensetive 'starts_with' search on relationship",
329         "required": false,
330         "type": "string"
331       },
332       {
333         "name": "sex",
334         "in": "query",
335         "description": "Case insensetive 'starts_with' search on sex",
336         "required": false,
337         "type": "string"
338       },
339       {
340         "name": "password",
341         "in": "query",
342         "description": "Case insensetive 'starts_with' search on password",
343         "required": false,
344         "type": "string"
345       },
346       {
347         "name": "flags",
348         "in": "query",
349         "description": "Case insensetive 'starts_with' search on flags",
350         "required": false,
351         "type": "string"
352       },
353       {
354         "name": "userid",
355         "in": "query",
356         "description": "Case insensetive 'starts_with' search on userid",
357         "required": false,
358         "type": "string"
359       },
360       {
361         "name": "opacnote",
362         "in": "query",
363         "description": "Case insensetive 'starts_with' search on opacnote",
364         "required": false,
365         "type": "string"
366       },
367       {
368         "name": "contactnote",
369         "in": "query",
370         "description": "Case insensetive 'starts_with' search on contactnote",
371         "required": false,
372         "type": "string"
373       },
374       {
375         "name": "sort1",
376         "in": "query",
377         "description": "Case insensetive 'starts_with' search on sort1",
378         "required": false,
379         "type": "string"
380       },
381       {
382         "name": "sort2",
383         "in": "query",
384         "description": "Case insensetive 'starts_with' search on sort2",
385         "required": false,
386         "type": "string"
387       },
388       {
389         "name": "altcontactfirstname",
390         "in": "query",
391         "description": "Case insensetive 'starts_with' search on altcontactfirstname",
392         "required": false,
393         "type": "string"
394       },
395       {
396         "name": "altcontactsurname",
397         "in": "query",
398         "description": "Case insensetive 'starts_with' search on altcontactsurname",
399         "required": false,
400         "type": "string"
401       },
402       {
403         "name": "altcontactaddress1",
404         "in": "query",
405         "description": "Case insensetive 'starts_with' search on altcontactaddress1",
406         "required": false,
407         "type": "string"
408       },
409       {
410         "name": "altcontactaddress2",
411         "in": "query",
412         "description": "Case insensetive 'starts_with' search on altcontactaddress2",
413         "required": false,
414         "type": "string"
415       },
416       {
417         "name": "altcontactaddress3",
418         "in": "query",
419         "description": "Case insensetive 'starts_with' search on altcontactaddress3",
420         "required": false,
421         "type": "string"
422       },
423       {
424         "name": "altcontactstate",
425         "in": "query",
426         "description": "Case insensetive 'starts_with' search on altcontactstate",
427         "required": false,
428         "type": "string"
429       },
430       {
431         "name": "altcontactzipcode",
432         "in": "query",
433         "description": "Case insensetive 'starts_with' search on altcontactzipcode",
434         "required": false,
435         "type": "string"
436       },
437       {
438         "name": "altcontactcountry",
439         "in": "query",
440         "description": "Case insensetive 'starts_with' search on altcontactcountry",
441         "required": false,
442         "type": "string"
443       },
444       {
445         "name": "altcontactphone",
446         "in": "query",
447         "description": "Case insensetive 'starts_with' search on altcontactphone",
448         "required": false,
449         "type": "string"
450       },
451       {
452         "name": "smsalertnumber",
453         "in": "query",
454         "description": "Case insensetive 'starts_with' search on smsalertnumber",
455         "required": false,
456         "type": "string"
457       },
458       {
459         "name": "sms_provider_id",
460         "in": "query",
461         "description": "Case insensetive 'starts_with' search on sms_provider_id",
462         "required": false,
463         "type": "string"
464       },
465       {
466         "name": "privacy",
467         "in": "query",
468         "description": "Case insensetive 'starts_with' search on privacy",
469         "required": false,
470         "type": "string"
471       },
472       {
473         "name": "privacy_guarantor_checkouts",
474         "in": "query",
475         "description": "Case insensetive 'starts_with' search on privacy_guarantor_checkouts",
476         "required": false,
477         "type": "string"
478       },
479       {
480         "name": "checkprevcheckout",
481         "in": "query",
482         "description": "Case insensetive 'starts_with' search on checkprevcheckout",
483         "required": false,
484         "type": "string"
485       },
486       {
487         "name": "updated_on",
488         "in": "query",
489         "description": "Case insensetive 'starts_with' search on updated_on",
490         "required": false,
491         "type": "string"
492       },
493       {
494         "name": "lastseen",
495         "in": "query",
496         "description": "Case insensetive 'starts_with' search on lastseen",
497         "required": false,
498         "type": "string"
499       },
500       {
501         "name": "lang",
502         "in": "query",
503         "description": "Case insensetive 'starts_with' search on lang",
504         "required": false,
505         "type": "string"
506       },
507       {
508         "name": "login_attempts",
509         "in": "query",
510         "description": "Case insensetive 'starts_with' search on login_attempts",
511         "required": false,
512         "type": "string"
513       },
514       {
515         "name": "overdrive_auth_token",
516         "in": "query",
517         "description": "Case insensetive 'starts_with' search on overdrive_auth_token",
518         "required": false,
519         "type": "string"
520       }],
521       "responses": {
522         "200": {
523           "description": "A list of patrons",
524           "schema": {
525             "type": "array",
526             "items": {
527               "$ref": "../definitions.json#/patron"
528             }
529           }
530         },
531         "401": {
532           "description": "Authentication required",
533           "schema": {
534             "$ref": "../definitions.json#/error"
535           }
536         },
537         "403": {
538           "description": "Access forbidden",
539           "schema": {
540             "$ref": "../definitions.json#/error"
541           }
542         },
543         "500": {
544           "description": "Internal server error",
545           "schema": {
546             "$ref": "../definitions.json#/error"
547           }
548         }
549       },
550       "x-koha-authorization": {
551         "permissions": {
552           "borrowers": "1"
553         }
554       }
555     },
556     "post": {
557       "operationId": "addPatron",
558       "tags": ["patrons"],
559       "parameters": [{
560         "name": "body",
561         "in": "body",
562         "description": "A JSON object containing information about the new patron",
563         "required": true,
564         "schema": {
565           "$ref": "../definitions.json#/patron"
566         }
567       }],
568       "consumes": ["application/json"],
569       "produces": ["application/json"],
570       "responses": {
571         "201": {
572           "description": "A successfully created patron",
573           "schema": {
574             "items": {
575               "$ref": "../definitions.json#/patron"
576             }
577           }
578         },
579         "400": {
580           "description": "Bad parameter",
581           "schema": {
582             "$ref": "../definitions.json#/error"
583           }
584         },
585         "401": {
586           "description": "Authentication required",
587           "schema": {
588             "$ref": "../definitions.json#/error"
589           }
590         },
591         "403": {
592           "description": "Access forbidden",
593           "schema": {
594             "$ref": "../definitions.json#/error"
595           }
596         },
597         "404": {
598           "description": "Resource not found",
599           "schema": {
600             "$ref": "../definitions.json#/error"
601           }
602         },
603         "409": {
604           "description": "Conflict in creating resource",
605           "schema": {
606             "$ref": "../definitions.json#/error"
607           }
608         },
609         "503": {
610           "description": "Under maintenance",
611           "schema": {
612             "$ref": "../definitions.json#/error"
613           }
614         },
615         "500": {
616           "description": "Internal server error",
617           "schema": {
618             "$ref": "../definitions.json#/error"
619           }
620         }
621       },
622       "x-koha-authorization": {
623         "permissions": {
624           "borrowers": "edit_borrowers"
625         }
626       }
627     }
628   },
629   "/patrons/{borrowernumber}": {
630     "get": {
631       "x-mojo-to": "Patron#get",
632       "operationId": "getPatron",
633       "tags": ["patrons"],
634       "parameters": [{
635         "$ref": "../parameters.json#/borrowernumberPathParam"
636       }],
637       "produces": [
638         "application/json"
639       ],
640       "responses": {
641         "200": {
642           "description": "A patron",
643           "schema": {
644             "$ref": "../definitions.json#/patron"
645           }
646         },
647         "401": {
648           "description": "Authentication required",
649           "schema": {
650             "$ref": "../definitions.json#/error"
651           }
652         },
653         "403": {
654           "description": "Access forbidden",
655           "schema": {
656             "$ref": "../definitions.json#/error"
657           }
658         },
659         "404": {
660           "description": "Patron not found",
661           "schema": {
662             "$ref": "../definitions.json#/error"
663           }
664         },
665         "500": {
666           "description": "Internal server error",
667           "schema": {
668             "$ref": "../definitions.json#/error"
669           }
670         },
671         "503": {
672           "description": "Under maintenance",
673           "schema": {
674             "$ref": "../definitions.json#/error"
675           }
676         }
677       },
678       "x-koha-authorization": {
679         "allow-owner": true,
680         "allow-guarantor": true,
681         "permissions": {
682           "borrowers": "edit_borrowers"
683         }
684       }
685     },
686     "put": {
687       "operationId": "editPatron",
688       "tags": ["patrons"],
689       "parameters": [
690         {
691           "$ref": "../parameters.json#/borrowernumberPathParam"
692         },
693         {
694           "name": "body",
695           "in": "body",
696           "description": "A JSON object containing new information about existing patron",
697           "required": true,
698           "schema": {
699             "$ref": "../definitions.json#/patron"
700           }
701         }
702       ],
703       "consumes": ["application/json"],
704       "produces": ["application/json"],
705       "responses": {
706         "200": {
707           "description": "A successfully updated patron",
708           "schema": {
709             "items": {
710               "$ref": "../definitions.json#/patron"
711             }
712           }
713         },
714         "202": {
715           "description": "Accepted and waiting for librarian verification",
716           "schema": {
717             "type": "object"
718           }
719         },
720         "204": {
721           "description": "No Content",
722           "schema": {
723             "type": "object"
724           }
725         },
726         "400": {
727           "description": "Bad parameter",
728           "schema": {
729             "$ref": "../definitions.json#/error"
730           }
731         },
732         "403": {
733           "description": "Access forbidden",
734           "schema": {
735             "$ref": "../definitions.json#/error"
736           }
737         },
738         "404": {
739           "description": "Resource not found",
740           "schema": {
741             "$ref": "../definitions.json#/error"
742           }
743         },
744         "409": {
745           "description": "Conflict in updating resource",
746           "schema": {
747             "$ref": "../definitions.json#/error"
748           }
749         },
750         "500": {
751           "description": "Internal server error",
752           "schema": {
753             "$ref": "../definitions.json#/error"
754           }
755         }
756       },
757       "x-koha-authorization": {
758         "allow-owner": true,
759         "allow-guarantor": true,
760         "permissions": {
761           "borrowers": "1"
762         }
763       }
764     },
765     "delete": {
766       "operationId": "deletePatron",
767       "tags": ["patrons"],
768       "parameters": [{
769         "$ref": "../parameters.json#/borrowernumberPathParam"
770       }],
771       "produces": ["application/json"],
772       "responses": {
773         "200": {
774           "description": "Patron deleted successfully",
775           "schema": {
776             "type": "object"
777           }
778         },
779         "400": {
780           "description": "Patron deletion failed",
781           "schema": {
782             "$ref": "../definitions.json#/error"
783           }
784         },
785         "401": {
786           "description": "Authentication required",
787           "schema": {
788             "$ref": "../definitions.json#/error"
789           }
790         },
791         "403": {
792           "description": "Access forbidden",
793           "schema": {
794             "$ref": "../definitions.json#/error"
795           }
796         },
797         "404": {
798           "description": "Patron not found",
799           "schema": {
800             "$ref": "../definitions.json#/error"
801           }
802         }
803       },
804       "x-koha-authorization": {
805         "permissions": {
806           "borrowers": "1"
807         }
808       }
809     }
810   }
811 }