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   "/public/biblios/{biblio_id}":
 181     $ref: "./paths/biblios.yaml#/~1public~1biblios~1{biblio_id}"
 182   "/public/biblios/{biblio_id}/items":
 183     $ref: "./paths/biblios.yaml#/~1public~1biblios~1{biblio_id}~1items"
 184   /public/libraries:
 185     $ref: ./paths/libraries.yaml#/~1public~1libraries
 186   "/public/libraries/{library_id}":
 187     $ref: "./paths/libraries.yaml#/~1public~1libraries~1{library_id}"
 188   "/public/patrons/{patron_id}/article_requests/{article_request_id}":
 189     $ref: "./paths/article_requests.yaml#/~1public~1patrons~1{patron_id}~1article_requests~1{article_request_id}"
 190   "/public/patrons/{patron_id}/guarantors/can_see_charges":
 191     $ref: "./paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1guarantors~1can_see_charges"
 192   "/public/patrons/{patron_id}/guarantors/can_see_checkouts":
 193     $ref: "./paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1guarantors~1can_see_checkouts"
 194   "/public/patrons/{patron_id}/password":
 195     $ref: "./paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1password"
 196   /quotes:
 197     $ref: ./paths/quotes.yaml#/~1quotes
 198   "/quotes/{quote_id}":
 199     $ref: "./paths/quotes.yaml#/~1quotes~1{quote_id}"
 200   /return_claims:
 201     $ref: ./paths/return_claims.yaml#/~1return_claims
 202   "/return_claims/{claim_id}":
 203     $ref: "./paths/return_claims.yaml#/~1return_claims~1{claim_id}"
 204   "/return_claims/{claim_id}/notes":
 205     $ref: "./paths/return_claims.yaml#/~1return_claims~1{claim_id}~1notes"
 206   "/return_claims/{claim_id}/resolve":
 207     $ref: "./paths/return_claims.yaml#/~1return_claims~1{claim_id}~1resolve"
 208   "/rotas/{rota_id}/stages/{stage_id}/position":
 209     $ref: "./paths/rotas.yaml#/~1rotas~1{rota_id}~1stages~1{stage_id}~1position"
 210   /suggestions:
 211     $ref: ./paths/suggestions.yaml#/~1suggestions
 212   "/suggestions/{suggestion_id}":
 213     $ref: "./paths/suggestions.yaml#/~1suggestions~1{suggestion_id}"
 214   /suggestions/managers:
 215     $ref: paths/suggestions.yaml#/~1suggestions~1managers
 216   /transfer_limits:
 217     $ref: ./paths/transfer_limits.yaml#/~1transfer_limits
 218   /transfer_limits/batch:
 219     $ref: ./paths/transfer_limits.yaml#/~1transfer_limits~1batch
 220   "/transfer_limits/{limit_id}":
 221     $ref: "./paths/transfer_limits.yaml#/~1transfer_limits~1{limit_id}"
 222 parameters:
 223   advancededitormacro_id_pp:
 224     description: Advanced editor macro internal identifier
 225     in: path
 226     name: advancededitormacro_id
 227     required: true
 228     type: integer
 229   biblio_id_pp:
 230     description: Record internal identifier
 231     in: path
 232     name: biblio_id
 233     required: true
 234     type: integer
 235   candidate_match_id_pp:
 236     description: Internal import record match identifier
 237     in: path
 238     name: candidate_match_id
 239     required: true
 240     type: integer
 241   cash_register_id_pp:
 242     description: Cash register internal identifier
 243     in: path
 244     name: cash_register_id
 245     required: true
 246     type: integer
 247   cashup_id_pp:
 248     description: Cashup internal identifier
 249     in: path
 250     name: cashup_id
 251     required: true
 252     type: integer
 253   checkout_id_pp:
 254     description: Internal checkout identifier
 255     in: path
 256     name: checkout_id
 257     required: true
 258     type: integer
 259   city_id_pp:
 260     description: City internal identifier
 261     in: path
 262     name: city_id
 263     required: true
 264     type: integer
 265   club_id_pp:
 266     description: Internal club identifier
 267     in: path
 268     name: club_id
 269     required: true
 270     type: integer
 271   fund_id_pp:
 272     description: Fund id
 273     in: path
 274     name: fund_id
 275     required: true
 276     type: integer
 277   hold_id_pp:
 278     description: Internal hold identifier
 279     in: path
 280     name: hold_id
 281     required: true
 282     type: integer
 283   import_batch_profile_id_pp:
 284     description: Internal profile identifier
 285     in: path
 286     name: import_batch_profile_id
 287     required: true
 288     type: integer
 289   import_record_id_pp:
 290     description: Internal import record identifier
 291     in: path
 292     name: import_record_id
 293     required: true
 294     type: integer
 295   item_id_pp:
 296     description: Internal item identifier
 297     in: path
 298     name: item_id
 299     required: true
 300     type: integer
 301   library_id_pp:
 302     description: Internal library identifier
 303     in: path
 304     name: library_id
 305     required: true
 306     type: string
 307   match:
 308     description: Matching criteria
 309     enum:
 310       - contains
 311       - exact
 312       - starts_with
 313       - ends_with
 314     in: query
 315     name: _match
 316     required: false
 317     type: string
 318   order_by:
 319     collectionFormat: csv
 320     description: Sorting criteria
 321     in: query
 322     items:
 323       type: string
 324     name: _order_by
 325     required: false
 326     type: array
 327   order_id_pp:
 328     description: Internal order identifier
 329     in: path
 330     name: order_id
 331     required: true
 332     type: integer
 333   page:
 334     description: "Page number, for paginated object listing"
 335     in: query
 336     name: _page
 337     required: false
 338     type: integer
 339   patron_id_pp:
 340     description: Internal patron identifier
 341     in: path
 342     name: patron_id
 343     required: true
 344     type: integer
 345   patron_id_qp:
 346     description: Internal patron identifier
 347     in: query
 348     name: patron_id
 349     type: integer
 350   per_page:
 351     description: "Page size, for paginated object listing"
 352     in: query
 353     name: _per_page
 354     required: false
 355     type: integer
 356   q_body:
 357     description: Query filter sent through request"s body
 358     in: body
 359     name: query
 360     required: false
 361     schema:
 362       type: object
 363   q_header:
 364     description: Query filter sent as a request header
 365     in: header
 366     name: x-koha-query
 367     required: false
 368     type: string
 369   q_param:
 370     description: Query filter sent as a request parameter
 371     in: query
 372     name: q
 373     required: false
 374     type: array
 375     items:
 376       type: string
 377     collectionFormat: multi
 378   quote_id_pp:
 379     description: Quote internal identifier
 380     in: path
 381     name: quote_id
 382     required: true
 383     type: integer
 384   request_id_header:
 385     description: Request id header
 386     in: header
 387     name: x-koha-request-id
 388     required: false
 389     type: integer
 390   seen_pp:
 391     description: Item was seen flag
 392     in: query
 393     name: seen
 394     required: false
 395     type: integer
 396   smtp_server_id_pp:
 397     description: SMTP server internal identifier
 398     in: path
 399     name: smtp_server_id
 400     required: true
 401     type: integer
 402   suggestion_id_pp:
 403     description: Internal suggestion identifier
 404     in: path
 405     name: suggestion_id
 406     required: true
 407     type: integer
 408   transfer_limit_id_pp:
 409     description: Internal transfer limit identifier
 410     in: path
 411     name: limit_id
 412     required: true
 413     type: string
 414   vendor_id_pp:
 415     description: Vendor id
 416     in: path
 417     name: vendor_id
 418     required: true
 419     type: integer
 420 info:
 421   title: Koha REST API
 422   version: "1"
 423   license:
 424     name: "GPL v3,"
 425     url: http://www.gnu.org/licenses/gpl.txt
 426   contact:
 427     name: Koha Development Team
 428     url: https://koha-community.org/
 429   description: |
 430     ## Introduction
 431
 432     This API is documented in **OpenAPI format**.
 433
 434     ## Authentication
 435
 436     The API supports the following authentication mechanisms
 437
 438     * HTTP Basic authentication
 439     * OAuth2 (client credentials grant)
 440     * Cookie-based
 441
 442     Both _Basic authentication_ and the _OAuth2_ flow, need to be enabled
 443     by system preferences.
 444
 445     ## Errors
 446
 447     The API uses standard HTTP status codes to indicate the success or failure
 448     of the API call. The body of the response will be JSON in the following format:
 449
 450     ```
 451     {
 452       "error": "Current settings prevent the passed due date to be applied",
 453       "error_code": "invalid_due_date"
 454     }
 455     ```
 456
 457     Note: Some routes might offer additional attributes in their error responses but that"s
 458     subject to change and thus not documented.
 459
 460     ## Filtering responses
 461
 462     The API allows for some advanced response filtering using a JSON based query syntax. The
 463     query can be added to the requests:
 464
 465     * as a query parameter `q=`
 466     * in the request body
 467     * in a special header `x-koha-query`
 468
 469     For simple field equality matches we can use `{ "fieldname": "value" }` where the fieldname
 470     matches one of the fields as described in the particular endpoints response object.
 471
 472     We can refine that with more complex matching clauses by nesting a the clause into the
 473     object; `{ "fieldname": { "clause": "value" } }`.
 474
 475     Available matching clauses include ">", "<", ">=", "<=", "-like", and "-not_like".
 476
 477     We can filter on multiple fields by adding them to the JSON respresentation. Adding at `HASH`
 478     level will result in an "AND" query, whilst combinding them in an `ARRAY` wilth result in an
 479     "OR" query: `{ "field1": "value2", "field2": "value2" }` will filter the response to only those
 480     results with both field1 containing value2 AND field2 containing value2 for example.
 481
 482     Additionally, if you are requesting related data be embedded into the response one can query
 483     on the related data using dot notation in the field names.
 484
 485     ### Examples
 486
 487     The following request would return any patron with firstname "Henry" and lastname "Acevedo";
 488
 489     `curl -u koha:koha --request GET "http://127.0.0.1:8081/api/v1/patrons/" --data-raw "{ "surname": "Acevedo", "firstname": "Henry" }"`
 490
 491     The following request would return any patron whose lastname begins with "Ace";
 492
 493     `curl -u koha:koha --request GET "http://127.0.0.1:8081/api/v1/patrons/" --data-raw "{ "surname": { "-like": "Ace%" }"`
 494
 495     The following request would return any patron whose lastname is "Acevedo" OR "Bernardo"
 496
 497     `curl -u koha:koha --request GET "http://127.0.0.1:8081/api/v1/patrons/" --data-raw "{ "surname": [ "Acevedo", "Bernardo" ] }"`
 498
 499     The following request embeds the related patron extended attributes data and filters on it.
 500
 501     `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" }'`
 502
 503     ## Special headers
 504
 505     ### x-koha-embed
 506
 507     This optional header allows the api consumer to request additional related data
 508     to be returned in the api response.  It also allows for cross referencing in the
 509     queries as described above. It accepts a comma delimited list of relation names.
 510
 511     Relations may on occasion also support dot delimited nesting to allow traversal.
 512
 513     ### x-koha-library
 514
 515     This optional header should be passed to give your api request a library
 516     context; If it is not included in the request, then the request context
 517     will default to using your api comsumer"s assigned home library.
 518 tags:
 519   - description: "Manage article requests\n"
 520     name: article_requests
 521     x-displayName: Article requests
 522   - description: "Manage bibliographic records\n"
 523     name: biblios
 524     x-displayName: Biblios
 525   - description: "Manage cash register cashups\n"
 526     name: cashups
 527     x-displayName: Cashups
 528   - description: "Manage checkouts\n"
 529     name: checkouts
 530     x-displayName: Checkouts
 531   - description: "Manage circulation rules\n"
 532     name: circulation_rules
 533     x-displayName: Circulation rules
 534   - description: "Manage cities\n"
 535     name: cities
 536     x-displayName: Cities
 537   - description: "Manage patron clubs\n"
 538     name: clubs
 539     x-displayName: Clubs
 540   - description: "Manage funds for the acquisitions module\n"
 541     name: funds
 542     x-displayName: Funds
 543   - description: "Manage holds\n"
 544     name: holds
 545     x-displayName: Holds
 546   - description: "Manage ILL module backends\n"
 547     name: illbackends
 548     x-displayName: ILL backends
 549   - description: "Manage ILL requests\n"
 550     name: illrequests
 551     x-displayName: ILL requests
 552   - description: "Manage items\n"
 553     name: items
 554     x-displayName: Items
 555   - description: "Manage libraries\n"
 556     name: libraries
 557     x-displayName: Libraries
 558   - description: "Manage macros\n"
 559     name: macros
 560     x-displayName: Macros
 561   - description: "Manage acquisition orders\n"
 562     name: orders
 563     x-displayName: Orders
 564   - description: "Handle OAuth flows\n"
 565     name: oauth
 566     x-displayName: OAuth
 567   - description: "Manage patrons\n"
 568     name: patrons
 569     x-displayName: Patrons
 570   - description: "Manage quotes\n"
 571     name: quotes
 572     x-displayName: Quotes
 573   - description: "Manage return claims\n"
 574     name: return_claims
 575     x-displayName: Return claims
 576   - description: "Manage rotas\n"
 577     name: rotas
 578     x-displayName: Rotas
 579   - description: "Manage SMTP servers configurations\n"
 580     name: smtp_servers
 581     x-displayName: SMTP servers
 582   - description: "Manage transfer limits\n"
 583     name: transfer
 584     x-displayName: Transfer limits
 585   - description: "Manage purchase suggestions\n"
 586     name: suggestions
 587     x-displayName: Purchase suggestions
 588   - description: "Manage vendors for the acquisitions module\n"
 589     name: vendors
 590     x-displayName: Vendors
 591   - description: "Manage batch import profiles\n"
 592     name: batch_import_profiles
 593     x-displayName: Batch import profiles