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 info:
 211   title: Koha REST API
 212   version: 1
 213   license:
 214     name: "GPL v3,"
 215     url: http://www.gnu.org/licenses/gpl.txt
 216   contact:
 217     name: Koha Development Team
 218     url: https://koha-community.org/
 219   description: |
 220     ## Introduction
 221
 222     This API is documented in **OpenAPI format**.
 223
 224     ## Authentication
 225
 226     The API supports the following authentication mechanisms
 227
 228     * HTTP Basic authentication
 229     * OAuth2 (client credentials grant)
 230     * Cookie-based
 231
 232     Both _Basic authentication_ and the _OAuth2_ flow, need to be enabled
 233     by system preferences.
 234
 235     ## Errors
 236
 237     The API uses standard HTTP status codes to indicate the success or failure
 238     of the API call. The body of the response will be JSON in the following format:
 239
 240     ```
 241     {
 242       "error": "Current settings prevent the passed due date to be applied",
 243       "error_code": "invalid_due_date"
 244     }
 245     ```
 246
 247     Note: Some routes might offer additional attributes in their error responses but that"s
 248     subject to change and thus not documented.
 249
 250     ## Filtering responses
 251
 252     The API allows for some advanced response filtering using a JSON based query syntax. The
 253     query can be added to the requests:
 254
 255     * as a query parameter `q=`
 256     * in the request body
 257     * in a special header `x-koha-query`
 258
 259     For simple field equality matches we can use `{ "fieldname": "value" }` where the fieldname
 260     matches one of the fields as described in the particular endpoints response object.
 261
 262     We can refine that with more complex matching clauses by nesting a the clause into the
 263     object; `{ "fieldname": { "clause": "value" } }`.
 264
 265     Available matching clauses include ">", "<", ">=", "<=", "-like", and "-not_like".
 266
 267     We can filter on multiple fields by adding them to the JSON respresentation. Adding at `HASH`
 268     level will result in an "AND" query, whilst combinding them in an `ARRAY` wilth result in an
 269     "OR" query: `{ "field1": "value2", "field2": "value2" }` will filter the response to only those
 270     results with both field1 containing value2 AND field2 containing value2 for example.
 271
 272     ### Examples
 273
 274     The following request would return any patron with firstname "Henry" and lastname "Acevedo";
 275
 276     `curl -u koha:koha --request GET "http://127.0.0.1:8081/api/v1/patrons/" --data-raw "{ "surname": "Acevedo", "firstname": "Henry" }"`
 277
 278     The following request would return any patron whose lastname begins with "Ace";
 279
 280     `curl -u koha:koha --request GET "http://127.0.0.1:8081/api/v1/patrons/" --data-raw "{ "surname": { "-like": "Ace%" }"`
 281
 282     The following request would return any patron whilse lastname is "Acevedo" OR "Bernardo"
 283
 284     `curl -u koha:koha --request GET "http://127.0.0.1:8081/api/v1/patrons/" --data-raw "{ "surname": [ "Acevedo", "Bernardo" ] }"`
 285
 286     ## Special headers
 287
 288     ### x-koha-library
 289
 290     This optional header should be passed to give your api request a library
 291     context; If it is not included in the request, then the request context
 292     will default to using your api comsumer"s assigned home library.
 293 tags:
 294   - description: "Manage article requests\n"
 295     name: article_requests
 296     x-displayName: Article requests
 297   - description: "Manage bibliographic records\n"
 298     name: biblios
 299     x-displayName: Biblios
 300   - description: "Manage cash register cashups\n"
 301     name: cashups
 302     x-displayName: Cashups
 303   - description: "Manage checkouts\n"
 304     name: checkouts
 305     x-displayName: Checkouts
 306   - description: "Manage circulation rules\n"
 307     name: circulation_rules
 308     x-displayName: Circulation rules
 309   - description: "Manage cities\n"
 310     name: cities
 311     x-displayName: Cities
 312   - description: "Manage patron clubs\n"
 313     name: clubs
 314     x-displayName: Clubs
 315   - description: "Manage funds for the acquisitions module\n"
 316     name: funds
 317     x-displayName: Funds
 318   - description: "Manage holds\n"
 319     name: holds
 320     x-displayName: Holds
 321   - description: "Manage ILL module backends\n"
 322     name: illbackends
 323     x-displayName: ILL backends
 324   - description: "Manage ILL requests\n"
 325     name: illrequests
 326     x-displayName: ILL requests
 327   - description: "Manage items\n"
 328     name: items
 329     x-displayName: Items
 330   - description: "Manage libraries\n"
 331     name: libraries
 332     x-displayName: Libraries
 333   - description: "Manage macros\n"
 334     name: macros
 335     x-displayName: Macros
 336   - description: "Manage acquisition orders\n"
 337     name: orders
 338     x-displayName: Orders
 339   - description: "Handle OAuth flows\n"
 340     name: oauth
 341     x-displayName: OAuth
 342   - description: "Manage patrons\n"
 343     name: patrons
 344     x-displayName: Patrons
 345   - description: "Manage quotes\n"
 346     name: quotes
 347     x-displayName: Quotes
 348   - description: "Manage return claims\n"
 349     name: return_claims
 350     x-displayName: Return claims
 351   - description: "Manage rotas\n"
 352     name: rotas
 353     x-displayName: Rotas
 354   - description: "Manage SMTP servers configurations\n"
 355     name: smtp_servers
 356     x-displayName: SMTP servers
 357   - description: "Manage transfer limits\n"
 358     name: transfer
 359     x-displayName: Transfer limits
 360   - description: "Manage purchase suggestions\n"
 361     name: suggestions
 362     x-displayName: Purchase suggestions
 363   - description: "Manage vendors for the acquisitions module\n"
 364     name: vendors
 365     x-displayName: Vendors
 366   - description: "Manage batch import profiles\n"
 367     name: batch_import_profiles
 368     x-displayName: Batch import profiles