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   /oauth/token:
  69     $ref: paths/oauth.yaml#/~1oauth~1token
  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   /acquisitions/funds:
  79     $ref: paths/acquisitions_funds.yaml#/~1acquisitions~1funds
  80   "/article_requests/{article_request_id}":
  81     $ref: paths/article_requests.yaml#/~1article_requests~1{article_request_id}
  82   "/biblios/{biblio_id}":
  83     $ref: paths/biblios.yaml#/~1biblios~1{biblio_id}
  84   "/biblios/{biblio_id}/checkouts":
  85     $ref: paths/biblios.yaml#/~1biblios~1{biblio_id}~1checkouts
  86   "/biblios/{biblio_id}/items":
  87     $ref: paths/biblios.yaml#/~1biblios~1{biblio_id}~1items
  88   "/biblios/{biblio_id}/pickup_locations":
  89     $ref: paths/biblios.yaml#/~1biblios~1{biblio_id}~1pickup_locations
  90   "/cash_registers/{cash_register_id}/cashups":
  91     $ref: paths/cash_registers.yaml#/~1cash_registers~1{cash_register_id}~1cashups
  92   "/cashups/{cashup_id}":
  93     $ref: paths/cash_registers.yaml#/~1cashups~1{cashup_id}
  94   /checkouts:
  95     $ref: paths/checkouts.yaml#/~1checkouts
  96   "/checkouts/{checkout_id}":
  97     $ref: paths/checkouts.yaml#/~1checkouts~1{checkout_id}
  98   "/checkouts/{checkout_id}/renewal":
  99     $ref: paths/checkouts.yaml#/~1checkouts~1{checkout_id}~1renewal
 100   /circulation-rules/kinds:
 101     $ref: paths/circulation-rules.yaml#/~1circulation-rules~1kinds
 102   /cities:
 103     $ref: paths/cities.yaml#/~1cities
 104   "/cities/{city_id}":
 105     $ref: paths/cities.yaml#/~1cities~1{city_id}
 106   "/clubs/{club_id}/holds":
 107     $ref: paths/clubs.yaml#/~1clubs~1{club_id}~1holds
 108   /config/smtp_servers:
 109     $ref: paths/config_smtp_servers.yaml#/~1config~1smtp_servers
 110   "/config/smtp_servers/{smtp_server_id}":
 111     $ref: paths/config_smtp_servers.yaml#/~1config~1smtp_servers~1{smtp_server_id}
 112   /holds:
 113     $ref: paths/holds.yaml#/~1holds
 114   "/holds/{hold_id}":
 115     $ref: paths/holds.yaml#/~1holds~1{hold_id}
 116   "/holds/{hold_id}/priority":
 117     $ref: paths/holds.yaml#/~1holds~1{hold_id}~1priority
 118   "/holds/{hold_id}/suspension":
 119     $ref: paths/holds.yaml#/~1holds~1{hold_id}~1suspension
 120   "/holds/{hold_id}/pickup_locations":
 121     $ref: paths/holds.yaml#/~1holds~1{hold_id}~1pickup_locations
 122   "/holds/{hold_id}/pickup_location":
 123     $ref: paths/holds.yaml#/~1holds~1{hold_id}~1pickup_location
 124   /items:
 125     $ref: paths/items.yaml#/~1items
 126   "/items/{item_id}":
 127     $ref: paths/items.yaml#/~1items~1{item_id}
 128   "/items/{item_id}/pickup_locations":
 129     $ref: paths/items.yaml#/~1items~1{item_id}~1pickup_locations
 130   /libraries:
 131     $ref: paths/libraries.yaml#/~1libraries
 132   "/libraries/{library_id}":
 133     $ref: paths/libraries.yaml#/~1libraries~1{library_id}
 134   /transfer_limits:
 135     $ref: paths/transfer_limits.yaml#/~1transfer_limits
 136   "/transfer_limits/{limit_id}":
 137     $ref: paths/transfer_limits.yaml#/~1transfer_limits~1{limit_id}
 138   /transfer_limits/batch:
 139     $ref: paths/transfer_limits.yaml#/~1transfer_limits~1batch
 140   "/checkouts/{checkout_id}/allows_renewal":
 141     $ref: paths/checkouts.yaml#/~1checkouts~1{checkout_id}~1allows_renewal
 142   /advanced_editor/macros:
 143     $ref: paths/advancededitormacros.yaml#/~1advanced_editor~1macros
 144   "/advanced_editor/macros/{advancededitormacro_id}":
 145     $ref: paths/advancededitormacros.yaml#/~1advanced_editor~1macros~1{advancededitormacro_id}
 146   /advanced_editor/macros/shared:
 147     $ref: paths/advancededitormacros.yaml#/~1advanced_editor~1macros~1shared
 148   "/advanced_editor/macros/shared/{advancededitormacro_id}":
 149     $ref: paths/advancededitormacros.yaml#/~1advanced_editor~1macros~1shared~1{advancededitormacro_id}
 150   /patrons:
 151     $ref: paths/patrons.yaml#/~1patrons
 152   "/patrons/{patron_id}":
 153     $ref: paths/patrons.yaml#/~1patrons~1{patron_id}
 154   "/patrons/{patron_id}/account":
 155     $ref: paths/patrons_account.yaml#/~1patrons~1{patron_id}~1account
 156   "/patrons/{patron_id}/account/credits":
 157     $ref: paths/patrons_account.yaml#/~1patrons~1{patron_id}~1account~1credits
 158   "/patrons/{patron_id}/extended_attributes":
 159     $ref: paths/patrons_extended_attributes.yaml#/~1patrons~1{patron_id}~1extended_attributes
 160   "/patrons/{patron_id}/extended_attributes/{extended_attribute_id}":
 161     $ref: paths/patrons_extended_attributes.yaml#/~1patrons~1{patron_id}~1extended_attributes~1{extended_attribute_id}
 162   "/patrons/{patron_id}/holds":
 163     $ref: paths/patrons_holds.yaml#/~1patrons~1{patron_id}~1holds
 164   "/patrons/{patron_id}/password":
 165     $ref: paths/patrons_password.yaml#/~1patrons~1{patron_id}~1password
 166   /ill_backends:
 167     $ref: paths/ill_backends.yaml#/~1ill_backends
 168   "/ill_backends/{ill_backend_id}":
 169     $ref: paths/ill_backends.yaml#/~1ill_backends~1{ill_backend_id}
 170   /illrequests:
 171     $ref: paths/illrequests.yaml#/~1illrequests
 172   /import_batch_profiles:
 173     $ref: paths/import_batch_profiles.yaml#/~1import_batch_profiles
 174   "/import_batch_profiles/{import_batch_profile_id}":
 175     $ref: paths/import_batch_profiles.yaml#/~1import_batch_profiles~1{import_batch_profile_id}
 176   "/rotas/{rota_id}/stages/{stage_id}/position":
 177     $ref: paths/rotas.yaml#/~1rotas~1{rota_id}~1stages~1{stage_id}~1position
 178   "/public/biblios/{biblio_id}":
 179     $ref: paths/biblios.yaml#/~1public~1biblios~1{biblio_id}
 180   "/public/biblios/{biblio_id}/items":
 181     $ref: paths/biblios.yaml#/~1public~1biblios~1{biblio_id}~1items
 182   /public/libraries:
 183     $ref: paths/libraries.yaml#/~1public~1libraries
 184   "/public/libraries/{library_id}":
 185     $ref: paths/libraries.yaml#/~1public~1libraries~1{library_id}
 186   "/public/patrons/{patron_id}/article_requests/{article_request_id}":
 187     $ref: paths/article_requests.yaml#/~1public~1patrons~1{patron_id}~1article_requests~1{article_request_id}
 188   "/public/patrons/{patron_id}/password":
 189     $ref: paths/public_patrons.yaml#/~1public~1patrons~1{patron_id}~1password
 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   /quotes:
 195     $ref: paths/quotes.yaml#/~1quotes
 196   "/quotes/{quote_id}":
 197     $ref: paths/quotes.yaml#/~1quotes~1{quote_id}
 198   /return_claims:
 199     $ref: paths/return_claims.yaml#/~1return_claims
 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   "/return_claims/{claim_id}":
 205     $ref: paths/return_claims.yaml#/~1return_claims~1{claim_id}
 206   /suggestions:
 207     $ref: paths/suggestions.yaml#/~1suggestions
 208   "/suggestions/{suggestion_id}":
 209     $ref: paths/suggestions.yaml#/~1suggestions~1{suggestion_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   - name: "article_requests"
 295     x-displayName: Article requests
 296     description: |
 297       Manage article requests
 298   - name: "biblios"
 299     x-displayName: Biblios
 300     description: |
 301       Manage bibliographic records
 302   - name: "cashups"
 303     x-displayName: Cashups
 304     description: |
 305       Manage cash register cashups
 306   - name: "checkouts"
 307     x-displayName: Checkouts
 308     description: |
 309       Manage checkouts
 310   - name: "circulation_rules"
 311     x-displayName: Circulation rules
 312     description: |
 313       Manage circulation rules
 314   - name: "cities"
 315     x-displayName: Cities
 316     description: |
 317       Manage cities
 318   - name: "clubs"
 319     x-displayName: Clubs
 320     description: |
 321       Manage patron clubs
 322   - name: "funds"
 323     x-displayName: Funds
 324     description: |
 325       Manage funds for the acquisitions module
 326   - name: "holds"
 327     x-displayName: Holds
 328     description: |
 329       Manage holds
 330   - name: "illbackends"
 331     x-displayName: ILL backends
 332     description: |
 333       Manage ILL module backends
 334   - name: "illrequests"
 335     x-displayName: ILL requests
 336     description: |
 337       Manage ILL requests
 338   - name: "items"
 339     x-displayName: Items
 340     description: |
 341       Manage items
 342   - name: "libraries"
 343     x-displayName: Libraries
 344     description: |
 345       Manage libraries
 346   - name: "macros"
 347     x-displayName: Macros
 348     description: |
 349       Manage macros
 350   - name: "orders"
 351     x-displayName: Orders
 352     description: |
 353       Manage acquisition orders
 354   - name: "oauth"
 355     x-displayName: "OAuth"
 356     description: |
 357       Handle OAuth flows
 358   - name: "patrons"
 359     x-displayName: Patrons
 360     description: |
 361       Manage patrons
 362   - name: "quotes"
 363     x-displayName: Quotes
 364     description: |
 365       Manage quotes
 366   - name: "return_claims"
 367     x-displayName: Return claims
 368     description: |
 369       Manage return claims
 370   - name: "rotas"
 371     x-displayName: Rotas
 372     description: |
 373       Manage rotas
 374   - name: "smtp_servers"
 375     x-displayName: SMTP servers
 376     description: |
 377       Manage SMTP servers configurations
 378   - name: "transfer"
 379     x-displayName: Transfer limits
 380     description: |
 381       Manage transfer limits
 382   - name: "suggestions"
 383     x-displayName: "Purchase suggestions"
 384     description: |
 385       Manage purchase suggestions
 386   - name: "vendors"
 387     x-displayName: "Vendors"
 388     description: |
 389       Manage vendors for the acquisitions module
 390   - name: "batch_import_profiles"
 391     x-displayName: Batch import profiles
 392     description: |
 393       Manage batch import profiles