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