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 "/biblios/{biblio_id}/pickup_locations":
 404   get:
 405     x-mojo-to: Biblios#pickup_locations
 406     operationId: getBiblioPickupLocations
 407     tags:
 408       - biblios
 409     summary: Get valid pickup locations for a biblio
 410     parameters:
 411       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 412       - name: patron_id
 413         in: query
 414         description: Internal patron identifier
 415         required: true
 416         type: integer
 417       - $ref: "../swagger.yaml#/parameters/match"
 418       - $ref: "../swagger.yaml#/parameters/order_by"
 419       - $ref: "../swagger.yaml#/parameters/page"
 420       - $ref: "../swagger.yaml#/parameters/per_page"
 421       - $ref: "../swagger.yaml#/parameters/q_param"
 422       - $ref: "../swagger.yaml#/parameters/q_body"
 423       - $ref: "../swagger.yaml#/parameters/q_header"
 424     consumes:
 425       - application/json
 426     produces:
 427       - application/json
 428     responses:
 429       "200":
 430         description: Biblio pickup locations
 431         schema:
 432           type: array
 433           items:
 434             $ref: "../swagger.yaml#/definitions/library"
 435       "400":
 436         description: Missing or wrong parameters
 437         schema:
 438           $ref: "../swagger.yaml#/definitions/error"
 439       "401":
 440         description: Authentication required
 441         schema:
 442           $ref: "../swagger.yaml#/definitions/error"
 443       "403":
 444         description: Access forbidden
 445         schema:
 446           $ref: "../swagger.yaml#/definitions/error"
 447       "404":
 448         description: Biblio not found
 449         schema:
 450           $ref: "../swagger.yaml#/definitions/error"
 451       "500":
 452         description: |
 453           Internal server error. Possible `error_code` attribute values:
 454
 455           * `internal_server_error`
 456         schema:
 457           $ref: "../swagger.yaml#/definitions/error"
 458       "503":
 459         description: Under maintenance
 460         schema:
 461           $ref: "../swagger.yaml#/definitions/error"
 462     x-koha-authorization:
 463       permissions:
 464         reserveforothers: place_holds
 465 "/public/biblios/{biblio_id}":
 466   get:
 467     x-mojo-to: Biblios#get_public
 468     operationId: getBiblioPublic
 469     tags:
 470       - biblios
 471     summary: Get biblio (public)
 472     parameters:
 473       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 474     produces:
 475       - application/marcxml+xml
 476       - application/marc-in-json
 477       - application/marc
 478       - text/plain
 479     responses:
 480       "200":
 481         description: A biblio
 482       "401":
 483         description: Authentication required
 484         schema:
 485           $ref: "../swagger.yaml#/definitions/error"
 486       "403":
 487         description: Access forbidden
 488         schema:
 489           $ref: "../swagger.yaml#/definitions/error"
 490       "404":
 491         description: Biblio not found
 492         schema:
 493           $ref: "../swagger.yaml#/definitions/error"
 494       "406":
 495         description: Not acceptable
 496         schema:
 497           type: array
 498           description: Accepted content-types
 499           items:
 500             type: string
 501       "500":
 502         description: |
 503           Internal server error. Possible `error_code` attribute values:
 504
 505           * `internal_server_error`
 506         schema:
 507           $ref: "../swagger.yaml#/definitions/error"
 508       "503":
 509         description: Under maintenance
 510         schema:
 511           $ref: "../swagger.yaml#/definitions/error"
 512 "/public/biblios/{biblio_id}/items":
 513   get:
 514     x-mojo-to: Biblios#get_items_public
 515     operationId: getBiblioItemsPublic
 516     tags:
 517       - biblios
 518       - items
 519     parameters:
 520       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 521       - $ref: "../swagger.yaml#/parameters/match"
 522       - $ref: "../swagger.yaml#/parameters/order_by"
 523       - $ref: "../swagger.yaml#/parameters/page"
 524       - $ref: "../swagger.yaml#/parameters/per_page"
 525       - $ref: "../swagger.yaml#/parameters/q_param"
 526       - $ref: "../swagger.yaml#/parameters/q_body"
 527       - $ref: "../swagger.yaml#/parameters/q_header"
 528     consumes:
 529       - application/json
 530     produces:
 531       - application/json
 532     responses:
 533       "200":
 534         description: A list of the items attached to the record
 535         schema:
 536           type: array
 537           items:
 538             $ref: "../swagger.yaml#/definitions/item"
 539       "401":
 540         description: Authentication required
 541         schema:
 542           $ref: "../swagger.yaml#/definitions/error"
 543       "403":
 544         description: Access forbidden
 545         schema:
 546           $ref: "../swagger.yaml#/definitions/error"
 547       "404":
 548         description: Biblio not found
 549         schema:
 550           $ref: "../swagger.yaml#/definitions/error"
 551       "406":
 552         description: Not acceptable
 553         schema:
 554           type: array
 555           description: Accepted content-types
 556           items:
 557             type: string
 558       "500":
 559         description: |
 560           Internal server error. Possible `error_code` attribute values:
 561
 562           * `internal_server_error`
 563         schema:
 564           $ref: "../swagger.yaml#/definitions/error"
 565       "503":
 566         description: Under maintenance
 567         schema:
 568           $ref: "../swagger.yaml#/definitions/error"
 569 "/public/biblios/{biblio_id}/ratings":
 570   post:
 571     x-mojo-to: Biblios#set_rating
 572     operationId: setBiblioRating
 573     tags:
 574       - biblios
 575     summary: set biblio rating (public)
 576     parameters:
 577       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 578       - name: body
 579         in: body
 580         description: A JSON object containing rating information
 581         schema:
 582           type: object
 583           properties:
 584             rating:
 585               description: the rating
 586               type:
 587                 - integer
 588                 - "null"
 589           required:
 590               - rating
 591           additionalProperties: false
 592     produces:
 593       - application/json
 594     responses:
 595       "200":
 596         description: Rating set
 597         schema:
 598           type: object
 599           properties:
 600             rating:
 601               description: user's rating
 602               type:
 603                 - number
 604                 - "null"
 605             average:
 606               description: average rating
 607               type: number
 608             count:
 609               description: number of ratings
 610               type: integer
 611           additionalProperties: false
 612       "401":
 613         description: Authentication required
 614         schema:
 615           $ref: "../swagger.yaml#/definitions/error"
 616       "403":
 617         description: Access forbidden
 618         schema:
 619           $ref: "../swagger.yaml#/definitions/error"
 620       "404":
 621         description: Biblio not found
 622         schema:
 623           $ref: "../swagger.yaml#/definitions/error"
 624       "500":
 625         description: |
 626           Internal server error. Possible `error_code` attribute values:
 627
 628           * `internal_server_error`
 629         schema:
 630           $ref: "../swagger.yaml#/definitions/error"
 631       "503":
 632         description: Under maintenance
 633         schema:
 634           $ref: "../swagger.yaml#/definitions/error"