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