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