koha-dev.rot13.org Git - srvgit/blob - 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. The
  54     query can be added to the requests:
  55
  56     * as a query parameter `q=`
  57     * in the request body
  58     * in a special header `x-koha-query`
  59
  60     For simple field equality matches we can use `{ "fieldname": "value" }` where the fieldname
  61     matches one of the fields as described in the particular endpoints response object.
  62
  63     We can refine that with more complex matching clauses by nesting a the clause into the
  64     object; `{ "fieldname": { "clause": "value" } }`.
  65
  66     Available matching clauses include ">", "<", ">=", "<=", "-like", and "-not_like".
  67
  68     We can filter on multiple fields by adding them to the JSON respresentation. Adding at `HASH`
  69     level will result in an 'AND' query, whilst combinding them in an `ARRAY` wilth result in an
  70     'OR' query: `{ "field1": 'value2', "field2": "value2" }` will filter the response to only those
  71     results with both field1 containing value2 AND field2 containing value2 for example.
  72
  73     ### Examples
  74
  75     The following request would return any patron with firstname "Henry" and lastname "Acevedo";
  76
  77     `curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "surname": "Acevedo", "firstname": "Henry" }'`
  78
  79     The following request would return any patron whose lastname begins with "Ace";
  80
  81     `curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "surname": { "-like": "Ace%" }'`
  82
  83     The following request would return any patron whilse lastname is 'Acevedo' OR 'Bernardo'
  84
  85     `curl -u koha:koha --request GET 'http://127.0.0.1:8081/api/v1/patrons/' --data-raw '{ "surname": [ "Acevedo", "Bernardo" ] }'`
  86
  87     ## Special headers
  88
  89     ### x-koha-library
  90
  91     This optional header should be passed to give your api request a library
  92     context; If it is not included in the request, then the request context
  93     will default to using your api comsumer's assigned home library.
  94 tags:
  95   - name: "article_requests"
  96     x-displayName: Article requests
  97     description: |
  98       Manage article requests
  99   - name: "biblios"
 100     x-displayName: Biblios
 101     description: |
 102       Manage bibliographic records
 103   - name: "cashups"
 104     x-displayName: Cashups
 105     description: |
 106       Manage cash register cashups
 107   - name: "checkouts"
 108     x-displayName: Checkouts
 109     description: |
 110       Manage checkouts
 111   - name: "circulation_rules"
 112     x-displayName: Circulation rules
 113     description: |
 114       Manage circulation rules
 115   - name: "cities"
 116     x-displayName: Cities
 117     description: |
 118       Manage cities
 119   - name: "clubs"
 120     x-displayName: Clubs
 121     description: |
 122       Manage patron clubs
 123   - name: "funds"
 124     x-displayName: Funds
 125     description: |
 126       Manage funds for the acquisitions module
 127   - name: "holds"
 128     x-displayName: Holds
 129     description: |
 130       Manage holds
 131   - name: "illbackends"
 132     x-displayName: ILL backends
 133     description: |
 134       Manage ILL module backends
 135   - name: "illrequests"
 136     x-displayName: ILL requests
 137     description: |
 138       Manage ILL requests
 139   - name: "items"
 140     x-displayName: Items
 141     description: |
 142       Manage items
 143   - name: "library"
 144     x-displayName: Libraries
 145     description: |
 146       Manage libraries
 147   - name: "macros"
 148     x-displayName: Macros
 149     description: |
 150       Manage macros
 151   - name: "orders"
 152     x-displayName: Orders
 153     description: |
 154       Manage acquisition orders
 155   - name: "oauth"
 156     x-displayName: "OAuth"
 157     description: |
 158       Handle OAuth flows
 159   - name: "patrons"
 160     x-displayName: Patrons
 161     description: |
 162       Manage patrons
 163   - name: "quotes"
 164     x-displayName: Quotes
 165     description: |
 166       Manage quotes
 167   - name: "return_claims"
 168     x-displayName: Return claims
 169     description: |
 170       Manage return claims
 171   - name: "rotas"
 172     x-displayName: Rotas
 173     description: |
 174       Manage rotas
 175   - name: "smtp_servers"
 176     x-displayName: SMTP servers
 177     description: |
 178       Manage SMTP servers configurations
 179   - name: "transfer"
 180     x-displayName: Transfer limits
 181     description: |
 182       Manage transfer limits
 183   - name: "suggestions"
 184     x-displayName: "Purchase suggestions"
 185     description: |
 186       Manage purchase suggestions
 187   - name: "vendors"
 188     x-displayName: "Vendors"
 189     description: |
 190       Manage vendors for the acquisitions module
 191   - name: "batch_import_profiles"
 192     x-displayName: Batch import profiles
 193     description: |
 194       Manage batch import profiles