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/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     Additionally, if you are requesting related data be embedded into the response one can query
 467     on the related data using dot notation in the field names.
 468
 469     ### Examples
 470
 471     The following request would return any patron with firstname "Henry" and lastname "Acevedo";
 472
 473     `curl -u koha:koha --request GET "http://127.0.0.1:8081/api/v1/patrons/" --data-raw "{ "surname": "Acevedo", "firstname": "Henry" }"`
 474
 475     The following request would return any patron whose lastname begins with "Ace";
 476
 477     `curl -u koha:koha --request GET "http://127.0.0.1:8081/api/v1/patrons/" --data-raw "{ "surname": { "-like": "Ace%" }"`
 478
 479     The following request would return any patron whose lastname is "Acevedo" OR "Bernardo"
 480
 481     `curl -u koha:koha --request GET "http://127.0.0.1:8081/api/v1/patrons/" --data-raw "{ "surname": [ "Acevedo", "Bernardo" ] }"`
 482
 483     The following request embeds the related patron extended attributes data and filters on it.
 484
 485     `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" }'`
 486
 487     ## Special headers
 488
 489     ### x-koha-embed
 490
 491     This optional header allows the api consumer to request additional related data
 492     to be returned in the api response.  It also allows for cross referencing in the
 493     queries as described above. It accepts a comma delimited list of relation names.
 494
 495     Relations may on occasion also support dot delimited nesting to allow traversal.
 496
 497     ### x-koha-library
 498
 499     This optional header should be passed to give your api request a library
 500     context; If it is not included in the request, then the request context
 501     will default to using your api comsumer"s assigned home library.
 502 tags:
 503   - description: "Manage article requests\n"
 504     name: article_requests
 505     x-displayName: Article requests
 506   - description: "Manage bibliographic records\n"
 507     name: biblios
 508     x-displayName: Biblios
 509   - description: "Manage cash register cashups\n"
 510     name: cashups
 511     x-displayName: Cashups
 512   - description: "Manage checkouts\n"
 513     name: checkouts
 514     x-displayName: Checkouts
 515   - description: "Manage circulation rules\n"
 516     name: circulation_rules
 517     x-displayName: Circulation rules
 518   - description: "Manage cities\n"
 519     name: cities
 520     x-displayName: Cities
 521   - description: "Manage patron clubs\n"
 522     name: clubs
 523     x-displayName: Clubs
 524   - description: "Manage funds for the acquisitions module\n"
 525     name: funds
 526     x-displayName: Funds
 527   - description: "Manage holds\n"
 528     name: holds
 529     x-displayName: Holds
 530   - description: "Manage ILL module backends\n"
 531     name: illbackends
 532     x-displayName: ILL backends
 533   - description: "Manage ILL requests\n"
 534     name: illrequests
 535     x-displayName: ILL requests
 536   - description: "Manage items\n"
 537     name: items
 538     x-displayName: Items
 539   - description: "Manage libraries\n"
 540     name: libraries
 541     x-displayName: Libraries
 542   - description: "Manage macros\n"
 543     name: macros
 544     x-displayName: Macros
 545   - description: "Manage acquisition orders\n"
 546     name: orders
 547     x-displayName: Orders
 548   - description: "Handle OAuth flows\n"
 549     name: oauth
 550     x-displayName: OAuth
 551   - description: "Manage patrons\n"
 552     name: patrons
 553     x-displayName: Patrons
 554   - description: "Manage quotes\n"
 555     name: quotes
 556     x-displayName: Quotes
 557   - description: "Manage return claims\n"
 558     name: return_claims
 559     x-displayName: Return claims
 560   - description: "Manage rotas\n"
 561     name: rotas
 562     x-displayName: Rotas
 563   - description: "Manage SMTP servers configurations\n"
 564     name: smtp_servers
 565     x-displayName: SMTP servers
 566   - description: "Manage transfer limits\n"
 567     name: transfer
 568     x-displayName: Transfer limits
 569   - description: "Manage purchase suggestions\n"
 570     name: suggestions
 571     x-displayName: Purchase suggestions
 572   - description: "Manage vendors for the acquisitions module\n"
 573     name: vendors
 574     x-displayName: Vendors
 575   - description: "Manage batch import profiles\n"
 576     name: batch_import_profiles
 577     x-displayName: Batch import profiles