api/v1/swagger/swagger.yaml

   1 ---
   2 swagger: "2.0"
   3 basePath: /api/v1
   4 paths:
   5   $ref: paths.json
   6 definitions:
   7   $ref: definitions.json
   8 parameters:
   9   $ref: parameters.json
  10 x-primitives:
  11   $ref: x-primitives.json
  12 info:
  13   title: Koha REST API
  14   version: "1"
  15   license:
  16     name: GPL v3,
  17     url: http://www.gnu.org/licenses/gpl.txt
  18   contact:
  19     name: Koha Development Team
  20     url: https://koha-community.org/
  21   description: |
  22     ## Introduction
  23
  24     This API is documented in **OpenAPI format**.
  25
  26     ## Authentication
  27
  28     The API supports the following authentication mechanisms
  29
  30     * HTTP Basic authentication
  31     * OAuth2 (client credentials grant)
  32     * Cookie-based
  33
  34     Both _Basic authentication_ and the _OAuth2_ flow, need to be enabled
  35     by system preferences.
  36
  37     ## Errors
  38
  39     The API uses standard HTTP status codes to indicate the success or failure
  40     of the API call. The body of the response will be JSON in the following format:
  41
  42     ```
  43     {
  44       "error": "patron not found"
  45     }
  46     ```
  47
  48     Note: Some routes might offer additional attributes in their error responses but that's
  49     subject to change and thus not documented.
  50
  51     ## Filtering responses
  52
  53     The API allows for some advanced response filtering using a json based query syntax that
  54     can be added as a query parameter, `q=` or in the request body.
  55
  56     For simple field equality matches we can use `{ "fieldname": "value" }` where the fieldname
  57     matches one of the fields as described in the particular endpoints response object.
  58
  59     We can refine that with more complex matching clauses by nesting a the clause into the
  60     object; `{ "fieldname": { "clause": "value" } }`.
  61
  62     Available matching clauses include ">", "<", ">=", "<=", "-like", and "-not_like".
  63
  64     We can filter on multiple fields by adding them to the JSON respresentation. Adding at `HASH`
  65     level will result in an 'AND' query, whilst combinding them in an `ARRAY` wilth result in an
  66     'OR' query: `{ "field1": 'value2', "field2": "value2" }` will filter the response to only those
  67     results with both field1 containing value2 AND field2 containing value2 for example.
  68
  69     ### Examples
  70
  71     The following request would return any patron with firstname "Henry" and lastname "Acevedo";
  72
  73     `curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "surname": "Acevedo", "firstname": "Henry" }'`
  74
  75     The following request would return any patron whose lastname begins with "Ace";
  76
  77     `curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "surname": { "-like": "Ace%" }'`
  78
  79     The following request would return any patron whilse lastname is 'Acevedo' OR 'Bernardo'
  80
  81     `curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "surname": [ "Acevedo", "Bernardo" ] }'`
  82
  83     ## Special headers
  84
  85     ### x-koha-library
  86
  87     This optional header should be passed to give your api request a library
  88     context; If it is not included in the request, then the request context
  89     will default to using your api comsumer's assigned home library.
  90 tags:
  91   - name: "article_requests"
  92     x-displayName: Article requests
  93     description: |
  94       Manage article requests
  95   - name: "biblios"
  96     x-displayName: Biblios
  97     description: |
  98       Manage bibliographic records
  99   - name: "cashups"
 100     x-displayName: Cashups
 101     description: |
 102       Manage cash register cashups
 103   - name: "checkouts"
 104     x-displayName: Checkouts
 105     description: |
 106       Manage checkouts
 107   - name: "circulation_rules"
 108     x-displayName: Circulation rules
 109     description: |
 110       Manage circulation rules
 111   - name: "cities"
 112     x-displayName: Cities
 113     description: |
 114       Manage cities
 115   - name: "clubs"
 116     x-displayName: Clubs
 117     description: |
 118       Manage patron clubs
 119   - name: "funds"
 120     x-displayName: Funds
 121     description: |
 122       Manage funds for the acquisitions module
 123   - name: "holds"
 124     x-displayName: Holds
 125     description: |
 126       Manage holds
 127   - name: "illbackends"
 128     x-displayName: ILL backends
 129     description: |
 130       Manage ILL module backends
 131   - name: "illrequests"
 132     x-displayName: ILL requests
 133     description: |
 134       Manage ILL requests
 135   - name: "items"
 136     x-displayName: Items
 137     description: |
 138       Manage items
 139   - name: "library"
 140     x-displayName: Libraries
 141     description: |
 142       Manage libraries
 143   - name: "macros"
 144     x-displayName: Macros
 145     description: |
 146       Manage macros
 147   - name: "orders"
 148     x-displayName: Orders
 149     description: |
 150       Manage acquisition orders
 151   - name: "oauth"
 152     x-displayName: "OAuth"
 153     description: |
 154       Handle OAuth flows
 155   - name: "patrons"
 156     x-displayName: Patrons
 157     description: |
 158       Manage patrons
 159   - name: "quotes"
 160     x-displayName: Quotes
 161     description: |
 162       Manage quotes
 163   - name: "return_claims"
 164     x-displayName: Return claims
 165     description: |
 166       Manage return claims
 167   - name: "rotas"
 168     x-displayName: Rotas
 169     description: |
 170       Manage rotas
 171   - name: "smtp_servers"
 172     x-displayName: SMTP servers
 173     description: |
 174       Manage SMTP servers configurations
 175   - name: "transfer"
 176     x-displayName: Transfer limits
 177     description: |
 178       Manage transfer limits
 179   - name: "suggestions"
 180     x-displayName: "Purchase suggestions"
 181     description: |
 182       Manage purchase suggestions
 183   - name: "vendors"
 184     x-displayName: "Vendors"
 185     description: |
 186       Manage vendors for the acquisitions module
 187   - name: "batch_import_profiles"
 188     x-displayName: Batch import profiles
 189     description: |
 190       Manage batch import profiles