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