api/v1/swagger/paths/biblios.yaml

   1 ---
   2 "/biblios":
   3   post:
   4     x-mojo-to: Biblios#add
   5     operationId: addBiblio
   6     tags:
   7       - biblios
   8     summary: Add biblio
   9     description: |
  10       Add a bibliographic record to Koha. An optional `x-framework-id`
  11       may be passed to specify the cataloguing framework to be used (instead
  12       of the default).
  13
  14       The request body is expected to contain a MARC record in the format specified in
  15       the `Content-type` header you pass. Possible values for this header and the corresponding
  16       record formats expected are listed below:
  17
  18       * application/marcxml+xml: MARCXML
  19       * application/marc-in-json: MARC-in-JSON
  20       * application/marc: Raw USMARC binary data
  21     parameters:
  22       - $ref: "../swagger.yaml#/parameters/framework_id_header"
  23       - $ref: "../swagger.yaml#/parameters/marc_schema_header"
  24       - $ref: "../swagger.yaml#/parameters/confirm_not_duplicate_header"
  25     produces:
  26       - application/json
  27     responses:
  28       "200":
  29         description: A biblio
  30       "400":
  31         description: Bad request
  32         schema:
  33           $ref: "../swagger.yaml#/definitions/error"
  34       "401":
  35         description: Authentication required
  36         schema:
  37           $ref: "../swagger.yaml#/definitions/error"
  38       "403":
  39         description: Access forbidden
  40         schema:
  41           $ref: "../swagger.yaml#/definitions/error"
  42       "406":
  43         description: Not acceptable
  44         schema:
  45           type: array
  46           description: Accepted content-types
  47           items:
  48             type: string
  49       "500":
  50         description: |
  51           Internal server error. Possible `error_code` attribute values:
  52
  53           * `internal_server_error`
  54         schema:
  55           $ref: "../swagger.yaml#/definitions/error"
  56       "503":
  57         description: Under maintenance
  58         schema:
  59           $ref: "../swagger.yaml#/definitions/error"
  60     x-koha-authorization:
  61       permissions:
  62         editcatalogue: edit_catalogue
  63   get:
  64     x-mojo-to: Biblios#list
  65     operationId: listBiblio
  66     tags:
  67       - biblios
  68     summary: List biblios
  69     parameters:
  70       - $ref: "../swagger.yaml#/parameters/page"
  71       - $ref: "../swagger.yaml#/parameters/per_page"
  72       - $ref: "../swagger.yaml#/parameters/match"
  73       - $ref: "../swagger.yaml#/parameters/order_by"
  74       - $ref: "../swagger.yaml#/parameters/q_param"
  75       - $ref: "../swagger.yaml#/parameters/q_body"
  76       - $ref: "../swagger.yaml#/parameters/q_header"
  77       - $ref: "../swagger.yaml#/parameters/request_id_header"
  78     produces:
  79       - application/json
  80       - application/marcxml+xml
  81       - application/marc-in-json
  82       - application/marc
  83       - text/plain
  84     responses:
  85       "200":
  86         description: A list of biblios
  87       "401":
  88         description: Authentication required
  89         schema:
  90           $ref: "../swagger.yaml#/definitions/error"
  91       "403":
  92         description: Access forbidden
  93         schema:
  94           $ref: "../swagger.yaml#/definitions/error"
  95       "404":
  96         description: Biblio not found
  97         schema:
  98           $ref: "../swagger.yaml#/definitions/error"
  99       "406":
 100         description: Not acceptable
 101         schema:
 102           type: array
 103           description: Accepted content-types
 104           items:
 105             type: string
 106       "500":
 107         description: |
 108           Internal server error. Possible `error_code` attribute values:
 109
 110           * `internal_server_error`
 111         schema:
 112           $ref: "../swagger.yaml#/definitions/error"
 113       "503":
 114         description: Under maintenance
 115         schema:
 116           $ref: "../swagger.yaml#/definitions/error"
 117     x-koha-authorization:
 118       permissions:
 119         catalogue: "1"
 120 "/biblios/{biblio_id}":
 121   get:
 122     x-mojo-to: Biblios#get
 123     operationId: getBiblio
 124     tags:
 125       - biblios
 126     summary: Get biblio
 127     parameters:
 128       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 129     produces:
 130       - application/json
 131       - application/marcxml+xml
 132       - application/marc-in-json
 133       - application/marc
 134       - text/plain
 135     responses:
 136       "200":
 137         description: A biblio
 138       "401":
 139         description: Authentication required
 140         schema:
 141           $ref: "../swagger.yaml#/definitions/error"
 142       "403":
 143         description: Access forbidden
 144         schema:
 145           $ref: "../swagger.yaml#/definitions/error"
 146       "404":
 147         description: Biblio not found
 148         schema:
 149           $ref: "../swagger.yaml#/definitions/error"
 150       "406":
 151         description: Not acceptable
 152         schema:
 153           type: array
 154           description: Accepted content-types
 155           items:
 156             type: string
 157       "500":
 158         description: |
 159           Internal server error. Possible `error_code` attribute values:
 160
 161           * `internal_server_error`
 162         schema:
 163           $ref: "../swagger.yaml#/definitions/error"
 164       "503":
 165         description: Under maintenance
 166         schema:
 167           $ref: "../swagger.yaml#/definitions/error"
 168     x-koha-authorization:
 169       permissions:
 170         catalogue: "1"
 171   delete:
 172     x-mojo-to: Biblios#delete
 173     operationId: deleteBiblio
 174     tags:
 175       - biblios
 176     summary: Delete biblio
 177     parameters:
 178       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 179     produces:
 180       - application/json
 181     responses:
 182       "204":
 183         description: Biblio deleted
 184         schema:
 185           type: string
 186       "401":
 187         description: Authentication required
 188         schema:
 189           $ref: "../swagger.yaml#/definitions/error"
 190       "403":
 191         description: Access forbidden
 192         schema:
 193           $ref: "../swagger.yaml#/definitions/error"
 194       "404":
 195         description: Biblio not found
 196         schema:
 197           $ref: "../swagger.yaml#/definitions/error"
 198       "409":
 199         description: Unable to perform action on biblio
 200         schema:
 201           $ref: "../swagger.yaml#/definitions/error"
 202       "500":
 203         description: Internal error
 204         schema:
 205           $ref: "../swagger.yaml#/definitions/error"
 206       "503":
 207         description: Under maintenance
 208         schema:
 209           $ref: "../swagger.yaml#/definitions/error"
 210     x-koha-authorization:
 211       permissions:
 212         editcatalogue: edit_catalogue
 213   put:
 214     x-mojo-to: Biblios#update
 215     operationId: updateBiblio
 216     tags:
 217       - biblios
 218     summary: Update biblio
 219     description: |
 220       Updates a bibliographic record to Koha. An optional `x-framework-id`
 221       may be passed, to specify the cataloguing framework to be used (instead
 222       of the default).
 223
 224       The request body is expected to contain a MARC record in the format specified by
 225       the `Content-type` header passed. Possible values for this headers and the corresponding
 226       record formats expected are listed below:
 227
 228       * application/marcxml+xml: MARCXML
 229       * application/marc-in-json: MARC-in-JSON
 230       * application/marc: Raw USMARC binary data
 231     parameters:
 232       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 233       - $ref: "../swagger.yaml#/parameters/framework_id_header"
 234       - $ref: "../swagger.yaml#/parameters/marc_schema_header"
 235       - $ref: "../swagger.yaml#/parameters/confirm_not_duplicate_header"
 236     produces:
 237       - application/json
 238     responses:
 239       "200":
 240         description: A biblio
 241       "400":
 242         description: Bad request
 243         schema:
 244           $ref: "../swagger.yaml#/definitions/error"
 245       "401":
 246         description: Authentication required
 247         schema:
 248           $ref: "../swagger.yaml#/definitions/error"
 249       "403":
 250         description: Access forbidden
 251         schema:
 252           $ref: "../swagger.yaml#/definitions/error"
 253       "404":
 254         description: Biblio not found
 255         schema:
 256           $ref: "../swagger.yaml#/definitions/error"
 257       "406":
 258         description: Not acceptable
 259         schema:
 260           type: array
 261           description: Accepted content-types
 262           items:
 263             type: string
 264       "500":
 265         description: |
 266           Internal server error. Possible `error_code` attribute values:
 267
 268           * `internal_server_error`
 269         schema:
 270           $ref: "../swagger.yaml#/definitions/error"
 271       "503":
 272         description: Under maintenance
 273         schema:
 274           $ref: "../swagger.yaml#/definitions/error"
 275     x-koha-authorization:
 276       permissions:
 277         editcatalogue: edit_catalogue
 278 "/biblios/{biblio_id}/checkouts":
 279   get:
 280     x-mojo-to: Biblios#get_checkouts
 281     operationId: listBiblioCheckouts
 282     tags:
 283       - checkouts
 284     summary: List checkouts for a biblio
 285     parameters:
 286       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 287       - $ref: "../swagger.yaml#/parameters/page"
 288       - $ref: "../swagger.yaml#/parameters/per_page"
 289       - $ref: "../swagger.yaml#/parameters/match"
 290       - $ref: "../swagger.yaml#/parameters/order_by"
 291       - $ref: "../swagger.yaml#/parameters/q_param"
 292       - $ref: "../swagger.yaml#/parameters/q_body"
 293       - $ref: "../swagger.yaml#/parameters/q_header"
 294       - $ref: "../swagger.yaml#/parameters/request_id_header"
 295       - name: x-koha-embed
 296         in: header
 297         required: false
 298         description: Embed list sent as a request header
 299         type: array
 300         items:
 301           type: string
 302           enum:
 303             - issuer
 304             - item
 305             - patron
 306             - library
 307         collectionFormat: csv
 308       - name: checked_in
 309         in: query
 310         description: By default, current checkouts are returned, when this is true then
 311           checked in checkouts are returned as result.
 312         type: boolean
 313     produces:
 314       - application/json
 315     responses:
 316       "200":
 317         description: A list of checkouts
 318         schema:
 319           $ref: "../swagger.yaml#/definitions/checkouts"
 320       "403":
 321         description: Access forbidden
 322         schema:
 323           $ref: "../swagger.yaml#/definitions/error"
 324       "404":
 325         description: Biblio not found
 326         schema:
 327           $ref: "../swagger.yaml#/definitions/error"
 328       "500":
 329         description: |
 330           Internal server error. Possible `error_code` attribute values:
 331
 332           * `internal_server_error`
 333         schema:
 334           $ref: "../swagger.yaml#/definitions/error"
 335       "503":
 336         description: Under maintenance
 337         schema:
 338           $ref: "../swagger.yaml#/definitions/error"
 339     x-koha-authorization:
 340       permissions:
 341         circulate: circulate_remaining_permissions
 342 "/biblios/{biblio_id}/items":
 343   get:
 344     x-mojo-to: Biblios#get_items
 345     operationId: getBiblioItems
 346     tags:
 347       - biblios
 348     summary: Get items for a biblio
 349     parameters:
 350       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 351       - name: x-koha-embed
 352         in: header
 353         required: false
 354         description: Embed list sent as a request header
 355         type: array
 356         items:
 357           type: string
 358           enum:
 359             - +strings
 360         collectionFormat: csv
 361       - $ref: "../swagger.yaml#/parameters/match"
 362       - $ref: "../swagger.yaml#/parameters/order_by"
 363       - $ref: "../swagger.yaml#/parameters/page"
 364       - $ref: "../swagger.yaml#/parameters/per_page"
 365       - $ref: "../swagger.yaml#/parameters/q_param"
 366       - $ref: "../swagger.yaml#/parameters/q_body"
 367       - $ref: "../swagger.yaml#/parameters/q_header"
 368       - $ref: "../swagger.yaml#/parameters/request_id_header"
 369     consumes:
 370       - application/json
 371     produces:
 372       - application/json
 373     responses:
 374       "200":
 375         description: A list of the items attached to the record
 376         schema:
 377           type: array
 378           items:
 379             $ref: "../swagger.yaml#/definitions/item"
 380       "401":
 381         description: Authentication required
 382         schema:
 383           $ref: "../swagger.yaml#/definitions/error"
 384       "403":
 385         description: Access forbidden
 386         schema:
 387           $ref: "../swagger.yaml#/definitions/error"
 388       "404":
 389         description: Biblio not found
 390         schema:
 391           $ref: "../swagger.yaml#/definitions/error"
 392       "406":
 393         description: Not acceptable
 394         schema:
 395           type: array
 396           description: Accepted content-types
 397           items:
 398             type: string
 399       "500":
 400         description: |
 401           Internal server error. Possible `error_code` attribute values:
 402
 403           * `internal_server_error`
 404         schema:
 405           $ref: "../swagger.yaml#/definitions/error"
 406       "503":
 407         description: Under maintenance
 408         schema:
 409           $ref: "../swagger.yaml#/definitions/error"
 410     x-koha-authorization:
 411       permissions:
 412         catalogue: "1"
 413 "/biblios/{biblio_id}/pickup_locations":
 414   get:
 415     x-mojo-to: Biblios#pickup_locations
 416     operationId: getBiblioPickupLocations
 417     tags:
 418       - biblios
 419     summary: Get valid pickup locations for a biblio
 420     parameters:
 421       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 422       - name: patron_id
 423         in: query
 424         description: Internal patron identifier
 425         required: true
 426         type: integer
 427       - $ref: "../swagger.yaml#/parameters/match"
 428       - $ref: "../swagger.yaml#/parameters/order_by"
 429       - $ref: "../swagger.yaml#/parameters/page"
 430       - $ref: "../swagger.yaml#/parameters/per_page"
 431       - $ref: "../swagger.yaml#/parameters/q_param"
 432       - $ref: "../swagger.yaml#/parameters/q_body"
 433       - $ref: "../swagger.yaml#/parameters/q_header"
 434     consumes:
 435       - application/json
 436     produces:
 437       - application/json
 438     responses:
 439       "200":
 440         description: Biblio pickup locations
 441         schema:
 442           type: array
 443           items:
 444             $ref: "../swagger.yaml#/definitions/library"
 445       "400":
 446         description: Missing or wrong parameters
 447         schema:
 448           $ref: "../swagger.yaml#/definitions/error"
 449       "401":
 450         description: Authentication required
 451         schema:
 452           $ref: "../swagger.yaml#/definitions/error"
 453       "403":
 454         description: Access forbidden
 455         schema:
 456           $ref: "../swagger.yaml#/definitions/error"
 457       "404":
 458         description: Biblio not found
 459         schema:
 460           $ref: "../swagger.yaml#/definitions/error"
 461       "500":
 462         description: |
 463           Internal server error. Possible `error_code` attribute values:
 464
 465           * `internal_server_error`
 466         schema:
 467           $ref: "../swagger.yaml#/definitions/error"
 468       "503":
 469         description: Under maintenance
 470         schema:
 471           $ref: "../swagger.yaml#/definitions/error"
 472     x-koha-authorization:
 473       permissions:
 474         reserveforothers: place_holds
 475 "/public/biblios/{biblio_id}":
 476   get:
 477     x-mojo-to: Biblios#get_public
 478     operationId: getBiblioPublic
 479     tags:
 480       - biblios
 481     summary: Get biblio (public)
 482     parameters:
 483       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 484     produces:
 485       - application/marcxml+xml
 486       - application/marc-in-json
 487       - application/marc
 488       - text/plain
 489     responses:
 490       "200":
 491         description: A biblio
 492       "401":
 493         description: Authentication required
 494         schema:
 495           $ref: "../swagger.yaml#/definitions/error"
 496       "403":
 497         description: Access forbidden
 498         schema:
 499           $ref: "../swagger.yaml#/definitions/error"
 500       "404":
 501         description: Biblio not found
 502         schema:
 503           $ref: "../swagger.yaml#/definitions/error"
 504       "406":
 505         description: Not acceptable
 506         schema:
 507           type: array
 508           description: Accepted content-types
 509           items:
 510             type: string
 511       "500":
 512         description: |
 513           Internal server error. Possible `error_code` attribute values:
 514
 515           * `internal_server_error`
 516         schema:
 517           $ref: "../swagger.yaml#/definitions/error"
 518       "503":
 519         description: Under maintenance
 520         schema:
 521           $ref: "../swagger.yaml#/definitions/error"
 522 "/public/biblios/{biblio_id}/items":
 523   get:
 524     x-mojo-to: Biblios#get_items_public
 525     operationId: getBiblioItemsPublic
 526     tags:
 527       - biblios
 528       - items
 529     parameters:
 530       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 531       - $ref: "../swagger.yaml#/parameters/match"
 532       - $ref: "../swagger.yaml#/parameters/order_by"
 533       - $ref: "../swagger.yaml#/parameters/page"
 534       - $ref: "../swagger.yaml#/parameters/per_page"
 535       - $ref: "../swagger.yaml#/parameters/q_param"
 536       - $ref: "../swagger.yaml#/parameters/q_body"
 537       - $ref: "../swagger.yaml#/parameters/q_header"
 538     consumes:
 539       - application/json
 540     produces:
 541       - application/json
 542     responses:
 543       "200":
 544         description: A list of the items attached to the record
 545         schema:
 546           type: array
 547           items:
 548             $ref: "../swagger.yaml#/definitions/item"
 549       "401":
 550         description: Authentication required
 551         schema:
 552           $ref: "../swagger.yaml#/definitions/error"
 553       "403":
 554         description: Access forbidden
 555         schema:
 556           $ref: "../swagger.yaml#/definitions/error"
 557       "404":
 558         description: Biblio not found
 559         schema:
 560           $ref: "../swagger.yaml#/definitions/error"
 561       "406":
 562         description: Not acceptable
 563         schema:
 564           type: array
 565           description: Accepted content-types
 566           items:
 567             type: string
 568       "500":
 569         description: |
 570           Internal server error. Possible `error_code` attribute values:
 571
 572           * `internal_server_error`
 573         schema:
 574           $ref: "../swagger.yaml#/definitions/error"
 575       "503":
 576         description: Under maintenance
 577         schema:
 578           $ref: "../swagger.yaml#/definitions/error"
 579 "/public/biblios/{biblio_id}/ratings":
 580   post:
 581     x-mojo-to: Biblios#set_rating
 582     operationId: setBiblioRating
 583     tags:
 584       - biblios
 585     summary: set biblio rating (public)
 586     parameters:
 587       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 588       - name: body
 589         in: body
 590         description: A JSON object containing rating information
 591         schema:
 592           type: object
 593           properties:
 594             rating:
 595               description: the rating
 596               type:
 597                 - integer
 598                 - "null"
 599           required:
 600               - rating
 601           additionalProperties: false
 602     produces:
 603       - application/json
 604     responses:
 605       "200":
 606         description: Rating set
 607         schema:
 608           type: object
 609           properties:
 610             rating:
 611               description: user's rating
 612               type:
 613                 - number
 614                 - "null"
 615             average:
 616               description: average rating
 617               type: number
 618             count:
 619               description: number of ratings
 620               type: integer
 621           additionalProperties: false
 622       "401":
 623         description: Authentication required
 624         schema:
 625           $ref: "../swagger.yaml#/definitions/error"
 626       "403":
 627         description: Access forbidden
 628         schema:
 629           $ref: "../swagger.yaml#/definitions/error"
 630       "404":
 631         description: Biblio not found
 632         schema:
 633           $ref: "../swagger.yaml#/definitions/error"
 634       "500":
 635         description: |
 636           Internal server error. Possible `error_code` attribute values:
 637
 638           * `internal_server_error`
 639         schema:
 640           $ref: "../swagger.yaml#/definitions/error"
 641       "503":
 642         description: Under maintenance
 643         schema:
 644           $ref: "../swagger.yaml#/definitions/error"