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       - $ref: "../swagger.yaml#/parameters/match"
 352       - $ref: "../swagger.yaml#/parameters/order_by"
 353       - $ref: "../swagger.yaml#/parameters/page"
 354       - $ref: "../swagger.yaml#/parameters/per_page"
 355       - $ref: "../swagger.yaml#/parameters/q_param"
 356       - $ref: "../swagger.yaml#/parameters/q_body"
 357       - $ref: "../swagger.yaml#/parameters/q_header"
 358       - $ref: "../swagger.yaml#/parameters/request_id_header"
 359     consumes:
 360       - application/json
 361     produces:
 362       - application/json
 363     responses:
 364       "200":
 365         description: A list of the items attached to the record
 366         schema:
 367           type: array
 368           items:
 369             $ref: "../swagger.yaml#/definitions/item"
 370       "401":
 371         description: Authentication required
 372         schema:
 373           $ref: "../swagger.yaml#/definitions/error"
 374       "403":
 375         description: Access forbidden
 376         schema:
 377           $ref: "../swagger.yaml#/definitions/error"
 378       "404":
 379         description: Biblio not found
 380         schema:
 381           $ref: "../swagger.yaml#/definitions/error"
 382       "406":
 383         description: Not acceptable
 384         schema:
 385           type: array
 386           description: Accepted content-types
 387           items:
 388             type: string
 389       "500":
 390         description: |
 391           Internal server error. Possible `error_code` attribute values:
 392
 393           * `internal_server_error`
 394         schema:
 395           $ref: "../swagger.yaml#/definitions/error"
 396       "503":
 397         description: Under maintenance
 398         schema:
 399           $ref: "../swagger.yaml#/definitions/error"
 400     x-koha-authorization:
 401       permissions:
 402         catalogue: "1"
 403   post:
 404     x-mojo-to: Biblios#add_item
 405     operationId: addBiblioItem
 406     tags:
 407       - biblios
 408     summary: Add an item for a biblio
 409     parameters:
 410       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 411       - name: body
 412         in: body
 413         description: A JSON object containing information about the new item
 414         required: true
 415         schema:
 416           $ref: "../swagger.yaml#/definitions/item"
 417     produces:
 418       - application/json
 419     responses:
 420       "201":
 421         description: Item added
 422         schema:
 423           $ref: "../swagger.yaml#/definitions/item"
 424       "400":
 425         description: Bad request
 426         schema:
 427           $ref: "../swagger.yaml#/definitions/error"
 428       "401":
 429         description: Authentication required
 430         schema:
 431           $ref: "../swagger.yaml#/definitions/error"
 432       "403":
 433         description: Access forbidden
 434         schema:
 435           $ref: "../swagger.yaml#/definitions/error"
 436       "404":
 437         description: Not found
 438         schema:
 439           $ref: "../swagger.yaml#/definitions/error"
 440       "500":
 441         description: |
 442           Internal server error. Possible `error_code` attribute values:
 443
 444           * `internal_server_error`
 445         schema:
 446           $ref: "../swagger.yaml#/definitions/error"
 447       "503":
 448         description: Under maintenance
 449         schema:
 450           $ref: "../swagger.yaml#/definitions/error"
 451     x-koha-authorization:
 452       permissions:
 453         editcatalogue: edit_catalogue
 454 "/biblios/{biblio_id}/pickup_locations":
 455   get:
 456     x-mojo-to: Biblios#pickup_locations
 457     operationId: getBiblioPickupLocations
 458     tags:
 459       - biblios
 460     summary: Get valid pickup locations for a biblio
 461     parameters:
 462       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 463       - name: patron_id
 464         in: query
 465         description: Internal patron identifier
 466         required: true
 467         type: integer
 468       - $ref: "../swagger.yaml#/parameters/match"
 469       - $ref: "../swagger.yaml#/parameters/order_by"
 470       - $ref: "../swagger.yaml#/parameters/page"
 471       - $ref: "../swagger.yaml#/parameters/per_page"
 472       - $ref: "../swagger.yaml#/parameters/q_param"
 473       - $ref: "../swagger.yaml#/parameters/q_body"
 474       - $ref: "../swagger.yaml#/parameters/q_header"
 475     consumes:
 476       - application/json
 477     produces:
 478       - application/json
 479     responses:
 480       "200":
 481         description: Biblio pickup locations
 482         schema:
 483           type: array
 484           items:
 485             $ref: "../swagger.yaml#/definitions/library"
 486       "400":
 487         description: Missing or wrong parameters
 488         schema:
 489           $ref: "../swagger.yaml#/definitions/error"
 490       "401":
 491         description: Authentication required
 492         schema:
 493           $ref: "../swagger.yaml#/definitions/error"
 494       "403":
 495         description: Access forbidden
 496         schema:
 497           $ref: "../swagger.yaml#/definitions/error"
 498       "404":
 499         description: Biblio not found
 500         schema:
 501           $ref: "../swagger.yaml#/definitions/error"
 502       "500":
 503         description: |
 504           Internal server error. Possible `error_code` attribute values:
 505
 506           * `internal_server_error`
 507         schema:
 508           $ref: "../swagger.yaml#/definitions/error"
 509       "503":
 510         description: Under maintenance
 511         schema:
 512           $ref: "../swagger.yaml#/definitions/error"
 513     x-koha-authorization:
 514       permissions:
 515         reserveforothers: place_holds
 516 "/public/biblios/{biblio_id}":
 517   get:
 518     x-mojo-to: Biblios#get_public
 519     operationId: getBiblioPublic
 520     tags:
 521       - biblios
 522     summary: Get biblio (public)
 523     parameters:
 524       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 525     produces:
 526       - application/marcxml+xml
 527       - application/marc-in-json
 528       - application/marc
 529       - text/plain
 530     responses:
 531       "200":
 532         description: A biblio
 533       "401":
 534         description: Authentication required
 535         schema:
 536           $ref: "../swagger.yaml#/definitions/error"
 537       "403":
 538         description: Access forbidden
 539         schema:
 540           $ref: "../swagger.yaml#/definitions/error"
 541       "404":
 542         description: Biblio not found
 543         schema:
 544           $ref: "../swagger.yaml#/definitions/error"
 545       "406":
 546         description: Not acceptable
 547         schema:
 548           type: array
 549           description: Accepted content-types
 550           items:
 551             type: string
 552       "500":
 553         description: |
 554           Internal server error. Possible `error_code` attribute values:
 555
 556           * `internal_server_error`
 557         schema:
 558           $ref: "../swagger.yaml#/definitions/error"
 559       "503":
 560         description: Under maintenance
 561         schema:
 562           $ref: "../swagger.yaml#/definitions/error"
 563 "/public/biblios/{biblio_id}/items":
 564   get:
 565     x-mojo-to: Biblios#get_items_public
 566     operationId: getBiblioItemsPublic
 567     tags:
 568       - biblios
 569       - items
 570     parameters:
 571       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 572       - $ref: "../swagger.yaml#/parameters/match"
 573       - $ref: "../swagger.yaml#/parameters/order_by"
 574       - $ref: "../swagger.yaml#/parameters/page"
 575       - $ref: "../swagger.yaml#/parameters/per_page"
 576       - $ref: "../swagger.yaml#/parameters/q_param"
 577       - $ref: "../swagger.yaml#/parameters/q_body"
 578       - $ref: "../swagger.yaml#/parameters/q_header"
 579       - name: x-koha-embed
 580         in: header
 581         required: false
 582         description: Embed list sent as a request header
 583         type: array
 584         items:
 585           type: string
 586           enum:
 587             - +strings
 588         collectionFormat: csv
 589     consumes:
 590       - application/json
 591     produces:
 592       - application/json
 593     responses:
 594       "200":
 595         description: A list of the items attached to the record
 596         schema:
 597           type: array
 598           items:
 599             $ref: "../swagger.yaml#/definitions/item"
 600       "401":
 601         description: Authentication required
 602         schema:
 603           $ref: "../swagger.yaml#/definitions/error"
 604       "403":
 605         description: Access forbidden
 606         schema:
 607           $ref: "../swagger.yaml#/definitions/error"
 608       "404":
 609         description: Biblio not found
 610         schema:
 611           $ref: "../swagger.yaml#/definitions/error"
 612       "406":
 613         description: Not acceptable
 614         schema:
 615           type: array
 616           description: Accepted content-types
 617           items:
 618             type: string
 619       "500":
 620         description: |
 621           Internal server error. Possible `error_code` attribute values:
 622
 623           * `internal_server_error`
 624         schema:
 625           $ref: "../swagger.yaml#/definitions/error"
 626       "503":
 627         description: Under maintenance
 628         schema:
 629           $ref: "../swagger.yaml#/definitions/error"
 630 "/public/biblios/{biblio_id}/ratings":
 631   post:
 632     x-mojo-to: Biblios#set_rating
 633     operationId: setBiblioRating
 634     tags:
 635       - biblios
 636     summary: set biblio rating (public)
 637     parameters:
 638       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 639       - name: body
 640         in: body
 641         description: A JSON object containing rating information
 642         schema:
 643           type: object
 644           properties:
 645             rating:
 646               description: the rating
 647               type:
 648                 - integer
 649                 - "null"
 650           required:
 651               - rating
 652           additionalProperties: false
 653     produces:
 654       - application/json
 655     responses:
 656       "200":
 657         description: Rating set
 658         schema:
 659           type: object
 660           properties:
 661             rating:
 662               description: user's rating
 663               type:
 664                 - number
 665                 - "null"
 666             average:
 667               description: average rating
 668               type: number
 669             count:
 670               description: number of ratings
 671               type: integer
 672           additionalProperties: false
 673       "401":
 674         description: Authentication required
 675         schema:
 676           $ref: "../swagger.yaml#/definitions/error"
 677       "403":
 678         description: Access forbidden
 679         schema:
 680           $ref: "../swagger.yaml#/definitions/error"
 681       "404":
 682         description: Biblio not found
 683         schema:
 684           $ref: "../swagger.yaml#/definitions/error"
 685       "500":
 686         description: |
 687           Internal server error. Possible `error_code` attribute values:
 688
 689           * `internal_server_error`
 690         schema:
 691           $ref: "../swagger.yaml#/definitions/error"
 692       "503":
 693         description: Under maintenance
 694         schema:
 695           $ref: "../swagger.yaml#/definitions/error"