api/v1/swagger/swagger.yaml

   1 ---
   2 swagger: "2.0"
   3 basePath: /api/v1
   4 definitions:
   5   account_line:
   6     $ref: ./definitions/account_line.yaml
   7   advancededitormacro:
   8     $ref: ./definitions/advancededitormacro.yaml
   9   allows_renewal:
  10     $ref: ./definitions/allows_renewal.yaml
  11   basket:
  12     $ref: ./definitions/basket.yaml
  13   cashup:
  14     $ref: ./definitions/cashup.yaml
  15   checkout:
  16     $ref: ./definitions/checkout.yaml
  17   checkouts:
  18     $ref: ./definitions/checkouts.yaml
  19   circ-rule-kind:
  20     $ref: ./definitions/circ-rule-kind.yaml
  21   city:
  22     $ref: ./definitions/city.yaml
  23   error:
  24     $ref: ./definitions/error.yaml
  25   fund:
  26     $ref: ./definitions/fund.yaml
  27   hold:
  28     $ref: ./definitions/hold.yaml
  29   holds:
  30     $ref: ./definitions/holds.yaml
  31   ill_backend:
  32     $ref: ./definitions/ill_backend.yaml
  33   ill_backends:
  34     $ref: ./definitions/ill_backends.yaml
  35   import_batch_profile:
  36     $ref: ./definitions/import_batch_profile.yaml
  37   import_batch_profiles:
  38     $ref: ./definitions/import_batch_profiles.yaml
  39   import_record_match:
  40     $ref: ./definitions/import_record_match.yaml
  41   invoice:
  42     $ref: ./definitions/invoice.yaml
  43   item:
  44     $ref: ./definitions/item.yaml
  45   library:
  46     $ref: ./definitions/library.yaml
  47   order:
  48     $ref: ./definitions/order.yaml
  49   patron:
  50     $ref: ./definitions/patron.yaml
  51   patron_account_credit:
  52     $ref: ./definitions/patron_account_credit.yaml
  53   patron_balance:
  54     $ref: ./definitions/patron_balance.yaml
  55   patron_extended_attribute:
  56     $ref: ./definitions/patron_extended_attribute.yaml
  57   quote:
  58     $ref: ./definitions/quote.yaml
  59   return_claim:
  60     $ref: ./definitions/return_claim.yaml
  61   smtp_server:
  62     $ref: ./definitions/smtp_server.yaml
  63   suggestion:
  64     $ref: ./definitions/suggestion.yaml
  65   transfer_limit:
  66     $ref: ./definitions/transfer_limit.yaml
  67   vendor:
  68     $ref: ./definitions/vendor.yaml
  69 paths:
  70   /acquisitions/baskets/managers:
  71     $ref: paths/acquisitions_baskets.yaml#/~1acquisitions~1baskets~1managers
  72   /acquisitions/funds:
  73     $ref: ./paths/acquisitions_funds.yaml#/~1acquisitions~1funds
  74   /acquisitions/funds/owners:
  75     $ref: paths/acquisitions_funds.yaml#/~1acquisitions~1funds~1owners
  76   /acquisitions/funds/users:
  77     $ref: paths/acquisitions_funds.yaml#/~1acquisitions~1funds~1users
  78   /acquisitions/orders:
  79     $ref: ./paths/acquisitions_orders.yaml#/~1acquisitions~1orders
  80   "/acquisitions/orders/{order_id}":
  81     $ref: "./paths/acquisitions_orders.yaml#/~1acquisitions~1orders~1{order_id}"
  82   /acquisitions/vendors:
  83     $ref: ./paths/acquisitions_vendors.yaml#/~1acquisitions~1vendors
  84   "/acquisitions/vendors/{vendor_id}":
  85     $ref: "./paths/acquisitions_vendors.yaml#/~1acquisitions~1vendors~1{vendor_id}"
  86   /advanced_editor/macros:
  87     $ref: ./paths/advancededitormacros.yaml#/~1advanced_editor~1macros
  88   /advanced_editor/macros/shared:
  89     $ref: ./paths/advancededitormacros.yaml#/~1advanced_editor~1macros~1shared
  90   "/advanced_editor/macros/shared/{advancededitormacro_id}":
  91     $ref: "./paths/advancededitormacros.yaml#/~1advanced_editor~1macros~1shared~1{advancededitormacro_id}"
  92   "/advanced_editor/macros/{advancededitormacro_id}":
  93     $ref: "./paths/advancededitormacros.yaml#/~1advanced_editor~1macros~1{advancededitormacro_id}"
  94   "/article_requests/{article_request_id}":
  95     $ref: "./paths/article_requests.yaml#/~1article_requests~1{article_request_id}"
  96   "/biblios/{biblio_id}":
  97     $ref: "./paths/biblios.yaml#/~1biblios~1{biblio_id}"
  98   "/biblios/{biblio_id}/checkouts":
  99     $ref: "./paths/biblios.yaml#/~1biblios~1{biblio_id}~1checkouts"
 100   "/biblios/{biblio_id}/items":
 101     $ref: "./paths/biblios.yaml#/~1biblios~1{biblio_id}~1items"
 102   "/biblios/{biblio_id}/pickup_locations":
 103     $ref: "./paths/biblios.yaml#/~1biblios~1{biblio_id}~1pickup_locations"
 104   "/cash_registers/{cash_register_id}/cashups":
 105     $ref: "./paths/cash_registers.yaml#/~1cash_registers~1{cash_register_id}~1cashups"
 106   "/cashups/{cashup_id}":
 107     $ref: "./paths/cash_registers.yaml#/~1cashups~1{cashup_id}"
 108   /checkouts:
 109     $ref: ./paths/checkouts.yaml#/~1checkouts
 110   "/checkouts/{checkout_id}":
 111     $ref: "./paths/checkouts.yaml#/~1checkouts~1{checkout_id}"
 112   "/checkouts/{checkout_id}/allows_renewal":
 113     $ref: "./paths/checkouts.yaml#/~1checkouts~1{checkout_id}~1allows_renewal"
 114   "/checkouts/{checkout_id}/renewal":
 115     $ref: "./paths/checkouts.yaml#/~1checkouts~1{checkout_id}~1renewal"
 116   /circulation-rules/kinds:
 117     $ref: ./paths/circulation-rules.yaml#/~1circulation-rules~1kinds
 118   /cities:
 119     $ref: ./paths/cities.yaml#/~1cities
 120   "/cities/{city_id}":
 121     $ref: "./paths/cities.yaml#/~1cities~1{city_id}"
 122   "/clubs/{club_id}/holds":
 123     $ref: "./paths/clubs.yaml#/~1clubs~1{club_id}~1holds"
 124   /config/smtp_servers:
 125     $ref: ./paths/config_smtp_servers.yaml#/~1config~1smtp_servers
 126   "/config/smtp_servers/{smtp_server_id}":
 127     $ref: "./paths/config_smtp_servers.yaml#/~1config~1smtp_servers~1{smtp_server_id}"
 128   /holds:
 129     $ref: ./paths/holds.yaml#/~1holds
 130   "/holds/{hold_id}":
 131     $ref: "./paths/holds.yaml#/~1holds~1{hold_id}"
 132   "/holds/{hold_id}/pickup_location":
 133     $ref: "./paths/holds.yaml#/~1holds~1{hold_id}~1pickup_location"
 134   "/holds/{hold_id}/pickup_locations":
 135     $ref: "./paths/holds.yaml#/~1holds~1{hold_id}~1pickup_locations"
 136   "/holds/{hold_id}/priority":
 137     $ref: "./paths/holds.yaml#/~1holds~1{hold_id}~1priority"
 138   "/holds/{hold_id}/suspension":
 139     $ref: "./paths/holds.yaml#/~1holds~1{hold_id}~1suspension"
 140   /ill_backends:
 141     $ref: ./paths/ill_backends.yaml#/~1ill_backends
 142   "/ill_backends/{ill_backend_id}":
 143     $ref: "./paths/ill_backends.yaml#/~1ill_backends~1{ill_backend_id}"
 144   /illrequests:
 145     $ref: ./paths/illrequests.yaml#/~1illrequests
 146   "/import/{import_batch_id}/records/{import_record_id}/matches/chosen":
 147     $ref: "./paths/import_record_matches.yaml#/~1import~1{import_batch_id}~1records~1{import_record_id}~1matches~1chosen"
 148   /import_batch_profiles:
 149     $ref: ./paths/import_batch_profiles.yaml#/~1import_batch_profiles
 150   "/import_batch_profiles/{import_batch_profile_id}":
 151     $ref: "./paths/import_batch_profiles.yaml#/~1import_batch_profiles~1{import_batch_profile_id}"
 152   /items:
 153     $ref: ./paths/items.yaml#/~1items
 154   "/items/{item_id}":
 155     $ref: "./paths/items.yaml#/~1items~1{item_id}"
 156   "/items/{item_id}/pickup_locations":
 157     $ref: "./paths/items.yaml#/~1items~1{item_id}~1pickup_locations"
 158   /libraries:
 159     $ref: ./paths/libraries.yaml#/~1libraries
 160   "/libraries/{library_id}":
 161     $ref: "./paths/libraries.yaml#/~1libraries~1{library_id}"
 162   /oauth/token:
 163     $ref: ./paths/oauth.yaml#/~1oauth~1token
 164   /patrons:
 165     $ref: ./paths/patrons.yaml#/~1patrons
 166   "/patrons/{patron_id}":
 167     $ref: "./paths/patrons.yaml#/~1patrons~1{patron_id}"
 168   "/patrons/{patron_id}/account":
 169     $ref: "./paths/patrons_account.yaml#/~1patrons~1{patron_id}~1account"
 170   "/patrons/{patron_id}/account/credits":
 171     $ref: "./paths/patrons_account.yaml#/~1patrons~1{patron_id}~1account~1credits"
 172   "/patrons/{patron_id}/extended_attributes":
 173     $ref: "./paths/patrons_extended_attributes.yaml#/~1patrons~1{patron_id}~1extended_attributes"
 174   "/patrons/{patron_id}/extended_attributes/{extended_attribute_id}":
 175     $ref: "./paths/patrons_extended_attributes.yaml#/~1patrons~1{patron_id}~1extended_attributes~1{extended_attribute_id}"
 176   "/patrons/{patron_id}/holds":
 177     $ref: "./paths/patrons_holds.yaml#/~1patrons~1{patron_id}~1holds"
 178   "/patrons/{patron_id}/password":
 179     $ref: "./paths/patrons_password.yaml#/~1patrons~1{patron_id}~1password"
 180   "/patrons/{patron_id}/password/expiration_date":
 181     $ref: "./paths/patrons_password.yaml#/~1patrons~1{patron_id}~1password~1expiration_date"
 182   "/public/biblios/{biblio_id}":
 183     $ref: "./paths/biblios.yaml#/~1public~1biblios~1{biblio_id}"
 184   "/public/biblios/{biblio_id}/items":
 185     $ref: "./paths/biblios.yaml#/~1public~1biblios~1{biblio_id}~1items"
 186   /public/libraries:
 187     $ref: ./paths/libraries.yaml#/~1public~1libraries
 188   "/public/libraries/{library_id}":
 189     $ref: "./paths/libraries.yaml#/~1public~1libraries~1{library_id}"
 190   "/public/patrons/{patron_id}/article_requests/{article_request_id}":
 191     $ref: "./paths/article_requests.yaml#/~1public~1patrons~1{patron_id}~1article_requests~1{article_request_id}"
 192   "/public/patrons/{patron_id}/guarantors/can_see_charges":
 193     $ref: "./paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1guarantors~1can_see_charges"
 194   "/public/patrons/{patron_id}/guarantors/can_see_checkouts":
 195     $ref: "./paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1guarantors~1can_see_checkouts"
 196   "/public/patrons/{patron_id}/password":
 197     $ref: "./paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1password"
 198   /quotes:
 199     $ref: ./paths/quotes.yaml#/~1quotes
 200   "/quotes/{quote_id}":
 201     $ref: "./paths/quotes.yaml#/~1quotes~1{quote_id}"
 202   /return_claims:
 203     $ref: ./paths/return_claims.yaml#/~1return_claims
 204   "/return_claims/{claim_id}":
 205     $ref: "./paths/return_claims.yaml#/~1return_claims~1{claim_id}"
 206   "/return_claims/{claim_id}/notes":
 207     $ref: "./paths/return_claims.yaml#/~1return_claims~1{claim_id}~1notes"
 208   "/return_claims/{claim_id}/resolve":
 209     $ref: "./paths/return_claims.yaml#/~1return_claims~1{claim_id}~1resolve"
 210   "/rotas/{rota_id}/stages/{stage_id}/position":
 211     $ref: "./paths/rotas.yaml#/~1rotas~1{rota_id}~1stages~1{stage_id}~1position"
 212   /suggestions:
 213     $ref: ./paths/suggestions.yaml#/~1suggestions
 214   "/suggestions/{suggestion_id}":
 215     $ref: "./paths/suggestions.yaml#/~1suggestions~1{suggestion_id}"
 216   /suggestions/managers:
 217     $ref: paths/suggestions.yaml#/~1suggestions~1managers
 218   /transfer_limits:
 219     $ref: ./paths/transfer_limits.yaml#/~1transfer_limits
 220   /transfer_limits/batch:
 221     $ref: ./paths/transfer_limits.yaml#/~1transfer_limits~1batch
 222   "/transfer_limits/{limit_id}":
 223     $ref: "./paths/transfer_limits.yaml#/~1transfer_limits~1{limit_id}"
 224 parameters:
 225   advancededitormacro_id_pp:
 226     description: Advanced editor macro internal identifier
 227     in: path
 228     name: advancededitormacro_id
 229     required: true
 230     type: integer
 231   biblio_id_pp:
 232     description: Record internal identifier
 233     in: path
 234     name: biblio_id
 235     required: true
 236     type: integer
 237   candidate_match_id_pp:
 238     description: Internal import record match identifier
 239     in: path
 240     name: candidate_match_id
 241     required: true
 242     type: integer
 243   cash_register_id_pp:
 244     description: Cash register internal identifier
 245     in: path
 246     name: cash_register_id
 247     required: true
 248     type: integer
 249   cashup_id_pp:
 250     description: Cashup internal identifier
 251     in: path
 252     name: cashup_id
 253     required: true
 254     type: integer
 255   checkout_id_pp:
 256     description: Internal checkout identifier
 257     in: path
 258     name: checkout_id
 259     required: true
 260     type: integer
 261   city_id_pp:
 262     description: City internal identifier
 263     in: path
 264     name: city_id
 265     required: true
 266     type: integer
 267   club_id_pp:
 268     description: Internal club identifier
 269     in: path
 270     name: club_id
 271     required: true
 272     type: integer
 273   fund_id_pp:
 274     description: Fund id
 275     in: path
 276     name: fund_id
 277     required: true
 278     type: integer
 279   hold_id_pp:
 280     description: Internal hold identifier
 281     in: path
 282     name: hold_id
 283     required: true
 284     type: integer
 285   import_batch_profile_id_pp:
 286     description: Internal profile identifier
 287     in: path
 288     name: import_batch_profile_id
 289     required: true
 290     type: integer
 291   import_record_id_pp:
 292     description: Internal import record identifier
 293     in: path
 294     name: import_record_id
 295     required: true
 296     type: integer
 297   item_id_pp:
 298     description: Internal item identifier
 299     in: path
 300     name: item_id
 301     required: true
 302     type: integer
 303   library_id_pp:
 304     description: Internal library identifier
 305     in: path
 306     name: library_id
 307     required: true
 308     type: string
 309   match:
 310     description: Matching criteria
 311     enum:
 312       - contains
 313       - exact
 314       - starts_with
 315       - ends_with
 316     in: query
 317     name: _match
 318     required: false
 319     type: string
 320   order_by:
 321     collectionFormat: csv
 322     description: Sorting criteria
 323     in: query
 324     items:
 325       type: string
 326     name: _order_by
 327     required: false
 328     type: array
 329   order_id_pp:
 330     description: Internal order identifier
 331     in: path
 332     name: order_id
 333     required: true
 334     type: integer
 335   page:
 336     description: "Page number, for paginated object listing"
 337     in: query
 338     name: _page
 339     required: false
 340     type: integer
 341   patron_id_pp:
 342     description: Internal patron identifier
 343     in: path
 344     name: patron_id
 345     required: true
 346     type: integer
 347   patron_id_qp:
 348     description: Internal patron identifier
 349     in: query
 350     name: patron_id
 351     type: integer
 352   per_page:
 353     description: "Page size, for paginated object listing"
 354     in: query
 355     name: _per_page
 356     required: false
 357     type: integer
 358   q_body:
 359     description: Query filter sent through request"s body
 360     in: body
 361     name: query
 362     required: false
 363     schema:
 364       type: object
 365   q_header:
 366     description: Query filter sent as a request header
 367     in: header
 368     name: x-koha-query
 369     required: false
 370     type: string
 371   q_param:
 372     description: Query filter sent as a request parameter
 373     in: query
 374     name: q
 375     required: false
 376     type: array
 377     items:
 378       type: string
 379     collectionFormat: multi
 380   quote_id_pp:
 381     description: Quote internal identifier
 382     in: path
 383     name: quote_id
 384     required: true
 385     type: integer
 386   request_id_header:
 387     description: Request id header
 388     in: header
 389     name: x-koha-request-id
 390     required: false
 391     type: integer
 392   seen_pp:
 393     description: Item was seen flag
 394     in: query
 395     name: seen
 396     required: false
 397     type: integer
 398   smtp_server_id_pp:
 399     description: SMTP server internal identifier
 400     in: path
 401     name: smtp_server_id
 402     required: true
 403     type: integer
 404   suggestion_id_pp:
 405     description: Internal suggestion identifier
 406     in: path
 407     name: suggestion_id
 408     required: true
 409     type: integer
 410   transfer_limit_id_pp:
 411     description: Internal transfer limit identifier
 412     in: path
 413     name: limit_id
 414     required: true
 415     type: string
 416   vendor_id_pp:
 417     description: Vendor id
 418     in: path
 419     name: vendor_id
 420     required: true
 421     type: integer
 422 info:
 423   title: Koha REST API
 424   version: "1"
 425   license:
 426     name: "GPL v3,"
 427     url: http://www.gnu.org/licenses/gpl.txt
 428   contact:
 429     name: Koha Development Team
 430     url: https://koha-community.org/
 431   description: |
 432     ## Introduction
 433
 434     This API is documented in **OpenAPI format**.
 435
 436     ## Authentication
 437
 438     The API supports the following authentication mechanisms
 439
 440     * HTTP Basic authentication
 441     * OAuth2 (client credentials grant)
 442     * Cookie-based
 443
 444     Both _Basic authentication_ and the _OAuth2_ flow, need to be enabled
 445     by system preferences.
 446
 447     ## Errors
 448
 449     The API uses standard HTTP status codes to indicate the success or failure
 450     of the API call. The body of the response will be JSON in the following format:
 451
 452     ```
 453     {
 454       "error": "Current settings prevent the passed due date to be applied",
 455       "error_code": "invalid_due_date"
 456     }
 457     ```
 458
 459     Note: Some routes might offer additional attributes in their error responses but that"s
 460     subject to change and thus not documented.
 461
 462     ## Filtering responses
 463
 464     The API allows for some advanced response filtering using a JSON based query syntax. The
 465     query can be added to the requests:
 466
 467     * as a query parameter `q=`
 468     * in the request body
 469     * in a special header `x-koha-query`
 470
 471     For simple field equality matches we can use `{ "fieldname": "value" }` where the fieldname
 472     matches one of the fields as described in the particular endpoints response object.
 473
 474     We can refine that with more complex matching clauses by nesting a the clause into the
 475     object; `{ "fieldname": { "clause": "value" } }`.
 476
 477     Available matching clauses include ">", "<", ">=", "<=", "-like", and "-not_like".
 478
 479     We can filter on multiple fields by adding them to the JSON respresentation. Adding at `HASH`
 480     level will result in an "AND" query, whilst combinding them in an `ARRAY` wilth result in an
 481     "OR" query: `{ "field1": "value2", "field2": "value2" }` will filter the response to only those
 482     results with both field1 containing value2 AND field2 containing value2 for example.
 483
 484     Additionally, if you are requesting related data be embedded into the response one can query
 485     on the related data using dot notation in the field names.
 486
 487     ### Examples
 488
 489     The following request would return any patron with firstname "Henry" and lastname "Acevedo";
 490
 491     `curl -u koha:koha --request GET "http://127.0.0.1:8081/api/v1/patrons/" --data-raw "{ "surname": "Acevedo", "firstname": "Henry" }"`
 492
 493     The following request would return any patron whose lastname begins with "Ace";
 494
 495     `curl -u koha:koha --request GET "http://127.0.0.1:8081/api/v1/patrons/" --data-raw "{ "surname": { "-like": "Ace%" }"`
 496
 497     The following request would return any patron whose lastname is "Acevedo" OR "Bernardo"
 498
 499     `curl -u koha:koha --request GET "http://127.0.0.1:8081/api/v1/patrons/" --data-raw "{ "surname": [ "Acevedo", "Bernardo" ] }"`
 500
 501     The following request embeds the related patron extended attributes data and filters on it.
 502
 503     `curl -u koha:koha =--request GET 'http://127.0.0.1:8081/api/v1/patrons/' --header 'x-koha-embed: extended_attributes' --data-raw '{ "extended_attributes.code": "internet", "extended_attributes.attribute": "1" }'`
 504
 505     ## Special headers
 506
 507     ### x-koha-embed
 508
 509     This optional header allows the api consumer to request additional related data
 510     to be returned in the api response.  It also allows for cross referencing in the
 511     queries as described above. It accepts a comma delimited list of relation names.
 512
 513     Relations may on occasion also support dot delimited nesting to allow traversal.
 514
 515     ### x-koha-library
 516
 517     This optional header should be passed to give your api request a library
 518     context; If it is not included in the request, then the request context
 519     will default to using your api comsumer"s assigned home library.
 520 tags:
 521   - description: "Manage article requests\n"
 522     name: article_requests
 523     x-displayName: Article requests
 524   - description: "Manage bibliographic records\n"
 525     name: biblios
 526     x-displayName: Biblios
 527   - description: "Manage cash register cashups\n"
 528     name: cashups
 529     x-displayName: Cashups
 530   - description: "Manage checkouts\n"
 531     name: checkouts
 532     x-displayName: Checkouts
 533   - description: "Manage circulation rules\n"
 534     name: circulation_rules
 535     x-displayName: Circulation rules
 536   - description: "Manage cities\n"
 537     name: cities
 538     x-displayName: Cities
 539   - description: "Manage patron clubs\n"
 540     name: clubs
 541     x-displayName: Clubs
 542   - description: "Manage funds for the acquisitions module\n"
 543     name: funds
 544     x-displayName: Funds
 545   - description: "Manage holds\n"
 546     name: holds
 547     x-displayName: Holds
 548   - description: "Manage ILL module backends\n"
 549     name: illbackends
 550     x-displayName: ILL backends
 551   - description: "Manage ILL requests\n"
 552     name: illrequests
 553     x-displayName: ILL requests
 554   - description: "Manage import batches\n"
 555     name: import_batches
 556     x-display-name: Import batches
 557   - description: "Manage items\n"
 558     name: items
 559     x-displayName: Items
 560   - description: "Manage libraries\n"
 561     name: libraries
 562     x-displayName: Libraries
 563   - description: "Manage macros\n"
 564     name: macros
 565     x-displayName: Macros
 566   - description: "Manage acquisition orders\n"
 567     name: orders
 568     x-displayName: Orders
 569   - description: "Handle OAuth flows\n"
 570     name: oauth
 571     x-displayName: OAuth
 572   - description: "Manage patrons\n"
 573     name: patrons
 574     x-displayName: Patrons
 575   - description: "Manage quotes\n"
 576     name: quotes
 577     x-displayName: Quotes
 578   - description: "Manage return claims\n"
 579     name: return_claims
 580     x-displayName: Return claims
 581   - description: "Manage rotas\n"
 582     name: rotas
 583     x-displayName: Rotas
 584   - description: "Manage SMTP servers configurations\n"
 585     name: smtp_servers
 586     x-displayName: SMTP servers
 587   - description: "Manage transfer limits\n"
 588     name: transfer
 589     x-displayName: Transfer limits
 590   - description: "Manage purchase suggestions\n"
 591     name: suggestions
 592     x-displayName: Purchase suggestions
 593   - description: "Manage vendors for the acquisitions module\n"
 594     name: vendors
 595     x-displayName: Vendors
 596   - description: "Manage batch import profiles\n"
 597     name: batch_import_profiles
 598     x-displayName: Batch import profiles