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/request_id_header"
  77     produces:
  78       - application/json
  79       - application/marcxml+xml
  80       - application/marc-in-json
  81       - application/marc
  82       - text/plain
  83     responses:
  84       "200":
  85         description: A list of biblios
  86       "401":
  87         description: Authentication required
  88         schema:
  89           $ref: "../swagger.yaml#/definitions/error"
  90       "403":
  91         description: Access forbidden
  92         schema:
  93           $ref: "../swagger.yaml#/definitions/error"
  94       "404":
  95         description: Biblio not found
  96         schema:
  97           $ref: "../swagger.yaml#/definitions/error"
  98       "406":
  99         description: Not acceptable
 100         schema:
 101           type: array
 102           description: Accepted content-types
 103           items:
 104             type: string
 105       "500":
 106         description: |
 107           Internal server error. Possible `error_code` attribute values:
 108
 109           * `internal_server_error`
 110         schema:
 111           $ref: "../swagger.yaml#/definitions/error"
 112       "503":
 113         description: Under maintenance
 114         schema:
 115           $ref: "../swagger.yaml#/definitions/error"
 116     x-koha-authorization:
 117       permissions:
 118         catalogue: "1"
 119 "/biblios/{biblio_id}":
 120   get:
 121     x-mojo-to: Biblios#get
 122     operationId: getBiblio
 123     tags:
 124       - biblios
 125     summary: Get biblio
 126     parameters:
 127       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 128     produces:
 129       - application/json
 130       - application/marcxml+xml
 131       - application/marc-in-json
 132       - application/marc
 133       - text/plain
 134     responses:
 135       "200":
 136         description: A biblio
 137       "401":
 138         description: Authentication required
 139         schema:
 140           $ref: "../swagger.yaml#/definitions/error"
 141       "403":
 142         description: Access forbidden
 143         schema:
 144           $ref: "../swagger.yaml#/definitions/error"
 145       "404":
 146         description: Biblio not found
 147         schema:
 148           $ref: "../swagger.yaml#/definitions/error"
 149       "406":
 150         description: Not acceptable
 151         schema:
 152           type: array
 153           description: Accepted content-types
 154           items:
 155             type: string
 156       "500":
 157         description: |
 158           Internal server error. Possible `error_code` attribute values:
 159
 160           * `internal_server_error`
 161         schema:
 162           $ref: "../swagger.yaml#/definitions/error"
 163       "503":
 164         description: Under maintenance
 165         schema:
 166           $ref: "../swagger.yaml#/definitions/error"
 167     x-koha-authorization:
 168       permissions:
 169         catalogue: "1"
 170   delete:
 171     x-mojo-to: Biblios#delete
 172     operationId: deleteBiblio
 173     tags:
 174       - biblios
 175     summary: Delete biblio
 176     parameters:
 177       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 178     produces:
 179       - application/json
 180     responses:
 181       "204":
 182         description: Biblio deleted
 183         schema:
 184           type: string
 185       "401":
 186         description: Authentication required
 187         schema:
 188           $ref: "../swagger.yaml#/definitions/error"
 189       "403":
 190         description: Access forbidden
 191         schema:
 192           $ref: "../swagger.yaml#/definitions/error"
 193       "404":
 194         description: Biblio not found
 195         schema:
 196           $ref: "../swagger.yaml#/definitions/error"
 197       "409":
 198         description: Unable to perform action on biblio
 199         schema:
 200           $ref: "../swagger.yaml#/definitions/error"
 201       "500":
 202         description: Internal error
 203         schema:
 204           $ref: "../swagger.yaml#/definitions/error"
 205       "503":
 206         description: Under maintenance
 207         schema:
 208           $ref: "../swagger.yaml#/definitions/error"
 209     x-koha-authorization:
 210       permissions:
 211         editcatalogue: edit_catalogue
 212   put:
 213     x-mojo-to: Biblios#update
 214     operationId: updateBiblio
 215     tags:
 216       - biblios
 217     summary: Update biblio
 218     description: |
 219       Updates a bibliographic record to Koha. An optional `x-framework-id`
 220       may be passed, to specify the cataloguing framework to be used (instead
 221       of the default).
 222
 223       The request body is expected to contain a MARC record in the format specified by
 224       the `Content-type` header passed. Possible values for this headers and the corresponding
 225       record formats expected are listed below:
 226
 227       * application/marcxml+xml: MARCXML
 228       * application/marc-in-json: MARC-in-JSON
 229       * application/marc: Raw USMARC binary data
 230     parameters:
 231       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 232       - $ref: "../swagger.yaml#/parameters/framework_id_header"
 233       - $ref: "../swagger.yaml#/parameters/marc_schema_header"
 234       - $ref: "../swagger.yaml#/parameters/confirm_not_duplicate_header"
 235     produces:
 236       - application/json
 237     responses:
 238       "200":
 239         description: A biblio
 240       "400":
 241         description: Bad request
 242         schema:
 243           $ref: "../swagger.yaml#/definitions/error"
 244       "401":
 245         description: Authentication required
 246         schema:
 247           $ref: "../swagger.yaml#/definitions/error"
 248       "403":
 249         description: Access forbidden
 250         schema:
 251           $ref: "../swagger.yaml#/definitions/error"
 252       "404":
 253         description: Biblio not found
 254         schema:
 255           $ref: "../swagger.yaml#/definitions/error"
 256       "406":
 257         description: Not acceptable
 258         schema:
 259           type: array
 260           description: Accepted content-types
 261           items:
 262             type: string
 263       "500":
 264         description: |
 265           Internal server error. Possible `error_code` attribute values:
 266
 267           * `internal_server_error`
 268         schema:
 269           $ref: "../swagger.yaml#/definitions/error"
 270       "503":
 271         description: Under maintenance
 272         schema:
 273           $ref: "../swagger.yaml#/definitions/error"
 274     x-koha-authorization:
 275       permissions:
 276         editcatalogue: edit_catalogue
 277 "/biblios/{biblio_id}/bookings":
 278   get:
 279     x-mojo-to: Biblios#get_bookings
 280     operationId: getBiblioBookings
 281     tags:
 282       - bookings
 283     summary: Get bookings for a biblio
 284     parameters:
 285       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 286       - $ref: "../swagger.yaml#/parameters/match"
 287       - $ref: "../swagger.yaml#/parameters/order_by"
 288       - $ref: "../swagger.yaml#/parameters/page"
 289       - $ref: "../swagger.yaml#/parameters/per_page"
 290       - $ref: "../swagger.yaml#/parameters/q_param"
 291       - $ref: "../swagger.yaml#/parameters/q_body"
 292       - name: x-koha-embed
 293         in: header
 294         required: false
 295         description: Embed list sent as a request header
 296         type: array
 297         items:
 298           type: string
 299           enum:
 300             - item
 301             - patron
 302         collectionFormat: csv
 303     consumes:
 304       - application/json
 305     produces:
 306       - application/json
 307     responses:
 308       "200":
 309         description: A list of the bookings attached to the record
 310         schema:
 311           type: array
 312           items:
 313             $ref: ../swagger.yaml#/definitions/booking
 314       "401":
 315         description: Authentication required
 316         schema:
 317           $ref: ../swagger.yaml#/definitions/error
 318       "403":
 319         description: Access forbidden
 320         schema:
 321           $ref: ../swagger.yaml#/definitions/error
 322       "404":
 323         description: Biblio not found
 324         schema:
 325           $ref: ../swagger.yaml#/definitions/error
 326       "406":
 327         description: Not acceptable
 328         schema:
 329           type: array
 330           description: Accepted content-types
 331           items:
 332             type: string
 333       "500":
 334         description: Internal server error
 335         schema:
 336           $ref: ../swagger.yaml#/definitions/error
 337       "503":
 338         description: Under maintenance
 339         schema:
 340           $ref: ../swagger.yaml#/definitions/error
 341     x-koha-authorization:
 342       permissions:
 343         circulate: "manage_bookings"
 344 "/biblios/{biblio_id}/checkouts":
 345   get:
 346     x-mojo-to: Biblios#get_checkouts
 347     operationId: listBiblioCheckouts
 348     tags:
 349       - checkouts
 350     summary: List checkouts for a biblio
 351     parameters:
 352       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 353       - $ref: "../swagger.yaml#/parameters/page"
 354       - $ref: "../swagger.yaml#/parameters/per_page"
 355       - $ref: "../swagger.yaml#/parameters/match"
 356       - $ref: "../swagger.yaml#/parameters/order_by"
 357       - $ref: "../swagger.yaml#/parameters/q_param"
 358       - $ref: "../swagger.yaml#/parameters/q_body"
 359       - $ref: "../swagger.yaml#/parameters/request_id_header"
 360       - name: x-koha-embed
 361         in: header
 362         required: false
 363         description: Embed list sent as a request header
 364         type: array
 365         items:
 366           type: string
 367           enum:
 368             - issuer
 369             - item
 370             - patron
 371             - library
 372         collectionFormat: csv
 373       - name: checked_in
 374         in: query
 375         description: By default, current checkouts are returned, when this is true then
 376           checked in checkouts are returned as result.
 377         type: boolean
 378     produces:
 379       - application/json
 380     responses:
 381       "200":
 382         description: A list of checkouts
 383         schema:
 384           $ref: "../swagger.yaml#/definitions/checkouts"
 385       "403":
 386         description: Access forbidden
 387         schema:
 388           $ref: "../swagger.yaml#/definitions/error"
 389       "404":
 390         description: Biblio not found
 391         schema:
 392           $ref: "../swagger.yaml#/definitions/error"
 393       "500":
 394         description: |
 395           Internal server error. Possible `error_code` attribute values:
 396
 397           * `internal_server_error`
 398         schema:
 399           $ref: "../swagger.yaml#/definitions/error"
 400       "503":
 401         description: Under maintenance
 402         schema:
 403           $ref: "../swagger.yaml#/definitions/error"
 404     x-koha-authorization:
 405       permissions:
 406         - circulate: circulate_remaining_permissions
 407         - circulate: manage_bookings
 408 "/biblios/{biblio_id}/items":
 409   get:
 410     x-mojo-to: Biblios#get_items
 411     operationId: getBiblioItems
 412     tags:
 413       - biblios
 414     summary: Get items for a biblio
 415     parameters:
 416       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 417       - name: x-koha-embed
 418         in: header
 419         required: false
 420         description: Embed list sent as a request header
 421         type: array
 422         items:
 423           type: string
 424           enum:
 425             - +strings
 426             - checkout
 427             - checkout.patron
 428             - transfer
 429             - first_hold
 430             - first_hold.patron
 431             - recall
 432             - recall.patron
 433             - item_type
 434             - in_bundle
 435             - bundle_host
 436             - course_item.course_reserves.course
 437             - cover_image_ids
 438             - item_group_item.item_group.description
 439             - serialitem.serial
 440         collectionFormat: csv
 441       - $ref: "../swagger.yaml#/parameters/match"
 442       - $ref: "../swagger.yaml#/parameters/order_by"
 443       - $ref: "../swagger.yaml#/parameters/page"
 444       - $ref: "../swagger.yaml#/parameters/per_page"
 445       - $ref: "../swagger.yaml#/parameters/q_param"
 446       - $ref: "../swagger.yaml#/parameters/q_body"
 447       - $ref: "../swagger.yaml#/parameters/request_id_header"
 448       - name: bookable
 449         in: query
 450         description: Limit to items that are bookable
 451         required: false
 452         type: boolean
 453     consumes:
 454       - application/json
 455     produces:
 456       - application/json
 457     responses:
 458       "200":
 459         description: A list of the items attached to the record
 460         schema:
 461           type: array
 462           items:
 463             $ref: "../swagger.yaml#/definitions/item"
 464       "401":
 465         description: Authentication required
 466         schema:
 467           $ref: "../swagger.yaml#/definitions/error"
 468       "403":
 469         description: Access forbidden
 470         schema:
 471           $ref: "../swagger.yaml#/definitions/error"
 472       "404":
 473         description: Biblio not found
 474         schema:
 475           $ref: "../swagger.yaml#/definitions/error"
 476       "406":
 477         description: Not acceptable
 478         schema:
 479           type: array
 480           description: Accepted content-types
 481           items:
 482             type: string
 483       "500":
 484         description: |
 485           Internal server error. Possible `error_code` attribute values:
 486
 487           * `internal_server_error`
 488         schema:
 489           $ref: "../swagger.yaml#/definitions/error"
 490       "503":
 491         description: Under maintenance
 492         schema:
 493           $ref: "../swagger.yaml#/definitions/error"
 494     x-koha-authorization:
 495       permissions:
 496         catalogue: "1"
 497   post:
 498     x-mojo-to: Biblios#add_item
 499     operationId: addBiblioItem
 500     tags:
 501       - biblios
 502     summary: Add an item for a biblio
 503     parameters:
 504       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 505       - name: body
 506         in: body
 507         description: A JSON object containing information about the new item
 508         required: true
 509         schema:
 510           $ref: "../swagger.yaml#/definitions/item"
 511     produces:
 512       - application/json
 513     responses:
 514       "201":
 515         description: Item added
 516         schema:
 517           $ref: "../swagger.yaml#/definitions/item"
 518       "400":
 519         description: Bad request
 520         schema:
 521           $ref: "../swagger.yaml#/definitions/error"
 522       "401":
 523         description: Authentication required
 524         schema:
 525           $ref: "../swagger.yaml#/definitions/error"
 526       "403":
 527         description: Access forbidden
 528         schema:
 529           $ref: "../swagger.yaml#/definitions/error"
 530       "404":
 531         description: Not found
 532         schema:
 533           $ref: "../swagger.yaml#/definitions/error"
 534       "409":
 535         description: Conflict
 536         schema:
 537           $ref: "../swagger.yaml#/definitions/error"
 538       "500":
 539         description: |
 540           Internal server error. Possible `error_code` attribute values:
 541
 542           * `internal_server_error`
 543         schema:
 544           $ref: "../swagger.yaml#/definitions/error"
 545       "503":
 546         description: Under maintenance
 547         schema:
 548           $ref: "../swagger.yaml#/definitions/error"
 549     x-koha-authorization:
 550       permissions:
 551         editcatalogue: edit_catalogue
 552 "/biblios/{biblio_id}/items/{item_id}":
 553   put:
 554     x-mojo-to: Biblios#update_item
 555     operationId: updateBiblioItem
 556     tags:
 557       - biblios
 558     summary: Update an item for a biblio
 559     parameters:
 560       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 561       - $ref: "../swagger.yaml#/parameters/item_id_pp"
 562       - name: body
 563         in: body
 564         description: A JSON object containing information about the item
 565         required: true
 566         schema:
 567           $ref: "../swagger.yaml#/definitions/item"
 568     produces:
 569       - application/json
 570     responses:
 571       "200":
 572         description: Item updated
 573         schema:
 574           $ref: "../swagger.yaml#/definitions/item"
 575       "400":
 576         description: Bad request
 577         schema:
 578           $ref: "../swagger.yaml#/definitions/error"
 579       "401":
 580         description: Authentication required
 581         schema:
 582           $ref: "../swagger.yaml#/definitions/error"
 583       "403":
 584         description: Access forbidden
 585         schema:
 586           $ref: "../swagger.yaml#/definitions/error"
 587       "404":
 588         description: Not found
 589         schema:
 590           $ref: "../swagger.yaml#/definitions/error"
 591       "409":
 592         description: Conflict
 593         schema:
 594           $ref: "../swagger.yaml#/definitions/error"
 595       "500":
 596         description: |
 597           Internal server error. Possible `error_code` attribute values:
 598
 599           * `internal_server_error`
 600         schema:
 601           $ref: "../swagger.yaml#/definitions/error"
 602       "503":
 603         description: Under maintenance
 604         schema:
 605           $ref: "../swagger.yaml#/definitions/error"
 606     x-koha-authorization:
 607       permissions:
 608         editcatalogue: edit_catalogue
 609 "/biblios/{biblio_id}/pickup_locations":
 610   get:
 611     x-mojo-to: Biblios#pickup_locations
 612     operationId: getBiblioPickupLocations
 613     tags:
 614       - biblios
 615     summary: Get valid pickup locations for a biblio
 616     parameters:
 617       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 618       - name: patron_id
 619         in: query
 620         description: Internal patron identifier
 621         required: true
 622         type: integer
 623       - $ref: "../swagger.yaml#/parameters/match"
 624       - $ref: "../swagger.yaml#/parameters/order_by"
 625       - $ref: "../swagger.yaml#/parameters/page"
 626       - $ref: "../swagger.yaml#/parameters/per_page"
 627       - $ref: "../swagger.yaml#/parameters/q_param"
 628       - $ref: "../swagger.yaml#/parameters/q_body"
 629     consumes:
 630       - application/json
 631     produces:
 632       - application/json
 633     responses:
 634       "200":
 635         description: Biblio pickup locations
 636         schema:
 637           type: array
 638           items:
 639             $ref: "../swagger.yaml#/definitions/library"
 640       "400":
 641         description: Missing or wrong parameters
 642         schema:
 643           $ref: "../swagger.yaml#/definitions/error"
 644       "401":
 645         description: Authentication required
 646         schema:
 647           $ref: "../swagger.yaml#/definitions/error"
 648       "403":
 649         description: Access forbidden
 650         schema:
 651           $ref: "../swagger.yaml#/definitions/error"
 652       "404":
 653         description: Biblio not found
 654         schema:
 655           $ref: "../swagger.yaml#/definitions/error"
 656       "500":
 657         description: |
 658           Internal server error. Possible `error_code` attribute values:
 659
 660           * `internal_server_error`
 661         schema:
 662           $ref: "../swagger.yaml#/definitions/error"
 663       "503":
 664         description: Under maintenance
 665         schema:
 666           $ref: "../swagger.yaml#/definitions/error"
 667     x-koha-authorization:
 668       permissions:
 669         reserveforothers: place_holds
 670 "/public/biblios/{biblio_id}":
 671   get:
 672     x-mojo-to: Biblios#get_public
 673     operationId: getBiblioPublic
 674     tags:
 675       - biblios
 676     summary: Get biblio (public)
 677     parameters:
 678       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 679     produces:
 680       - application/marcxml+xml
 681       - application/marc-in-json
 682       - application/marc
 683       - text/plain
 684     responses:
 685       "200":
 686         description: A biblio
 687       "401":
 688         description: Authentication required
 689         schema:
 690           $ref: "../swagger.yaml#/definitions/error"
 691       "403":
 692         description: Access forbidden
 693         schema:
 694           $ref: "../swagger.yaml#/definitions/error"
 695       "404":
 696         description: Biblio not found
 697         schema:
 698           $ref: "../swagger.yaml#/definitions/error"
 699       "406":
 700         description: Not acceptable
 701         schema:
 702           type: array
 703           description: Accepted content-types
 704           items:
 705             type: string
 706       "500":
 707         description: |
 708           Internal server error. Possible `error_code` attribute values:
 709
 710           * `internal_server_error`
 711         schema:
 712           $ref: "../swagger.yaml#/definitions/error"
 713       "503":
 714         description: Under maintenance
 715         schema:
 716           $ref: "../swagger.yaml#/definitions/error"
 717 "/public/biblios/{biblio_id}/items":
 718   get:
 719     x-mojo-to: Biblios#get_items_public
 720     operationId: getBiblioItemsPublic
 721     tags:
 722       - biblios
 723       - items
 724     parameters:
 725       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 726       - $ref: "../swagger.yaml#/parameters/match"
 727       - $ref: "../swagger.yaml#/parameters/order_by"
 728       - $ref: "../swagger.yaml#/parameters/page"
 729       - $ref: "../swagger.yaml#/parameters/per_page"
 730       - $ref: "../swagger.yaml#/parameters/q_param"
 731       - $ref: "../swagger.yaml#/parameters/q_body"
 732       - name: x-koha-embed
 733         in: header
 734         required: false
 735         description: Embed list sent as a request header
 736         type: array
 737         items:
 738           type: string
 739           enum:
 740             - +strings
 741         collectionFormat: csv
 742     consumes:
 743       - application/json
 744     produces:
 745       - application/json
 746     responses:
 747       "200":
 748         description: A list of the items attached to the record
 749         schema:
 750           type: array
 751           items:
 752             $ref: "../swagger.yaml#/definitions/item"
 753       "401":
 754         description: Authentication required
 755         schema:
 756           $ref: "../swagger.yaml#/definitions/error"
 757       "403":
 758         description: Access forbidden
 759         schema:
 760           $ref: "../swagger.yaml#/definitions/error"
 761       "404":
 762         description: Biblio not found
 763         schema:
 764           $ref: "../swagger.yaml#/definitions/error"
 765       "406":
 766         description: Not acceptable
 767         schema:
 768           type: array
 769           description: Accepted content-types
 770           items:
 771             type: string
 772       "500":
 773         description: |
 774           Internal server error. Possible `error_code` attribute values:
 775
 776           * `internal_server_error`
 777         schema:
 778           $ref: "../swagger.yaml#/definitions/error"
 779       "503":
 780         description: Under maintenance
 781         schema:
 782           $ref: "../swagger.yaml#/definitions/error"
 783 "/public/biblios/{biblio_id}/ratings":
 784   post:
 785     x-mojo-to: Biblios#set_rating
 786     operationId: setBiblioRating
 787     tags:
 788       - biblios
 789     summary: set biblio rating (public)
 790     parameters:
 791       - $ref: "../swagger.yaml#/parameters/biblio_id_pp"
 792       - name: body
 793         in: body
 794         description: A JSON object containing rating information
 795         schema:
 796           type: object
 797           properties:
 798             rating:
 799               description: the rating
 800               type:
 801                 - integer
 802                 - "null"
 803           required:
 804               - rating
 805           additionalProperties: false
 806     produces:
 807       - application/json
 808     responses:
 809       "200":
 810         description: Rating set
 811         schema:
 812           type: object
 813           properties:
 814             rating:
 815               description: user's rating
 816               type:
 817                 - number
 818                 - "null"
 819             average:
 820               description: average rating
 821               type: number
 822             count:
 823               description: number of ratings
 824               type: integer
 825           additionalProperties: false
 826       "401":
 827         description: Authentication required
 828         schema:
 829           $ref: "../swagger.yaml#/definitions/error"
 830       "403":
 831         description: Access forbidden
 832         schema:
 833           $ref: "../swagger.yaml#/definitions/error"
 834       "404":
 835         description: Biblio not found
 836         schema:
 837           $ref: "../swagger.yaml#/definitions/error"
 838       "500":
 839         description: |
 840           Internal server error. Possible `error_code` attribute values:
 841
 842           * `internal_server_error`
 843         schema:
 844           $ref: "../swagger.yaml#/definitions/error"
 845       "503":
 846         description: Under maintenance
 847         schema:
 848           $ref: "../swagger.yaml#/definitions/error"