BookStack Code Mirror - bookstack/blob - resources/views/api-docs/parts/getting-started.blade.php

   1 <h1 class="list-heading text-capitals mb-l">Getting Started</h1>
   2
   3 <p class="mb-none">
   4     This documentation covers use of the REST API. <br>
   5     Examples of API usage, in a variety of programming languages, can be found in the <a href="https://github.com/BookStackApp/api-scripts" target="_blank" rel="noopener noreferrer">BookStack api-scripts repo on GitHub</a>.
   6
   7     <br> <br>
   8     Some alternative options for extension and customization can be found below:
   9 </p>
  10
  11 <ul>
  12     <li>
  13         <a href="{{ url('/settings/webhooks') }}" target="_blank" rel="noopener noreferrer">Webhooks</a> -
  14         HTTP POST calls upon events occurring in BookStack.
  15     </li>
  16     <li>
  17         <a href="https://github.com/BookStackApp/BookStack/blob/development/dev/docs/visual-theme-system.md" target="_blank" rel="noopener noreferrer">Visual Theme System</a> -
  18         Methods to override views, translations and icons within BookStack.
  19     </li>
  20     <li>
  21         <a href="https://github.com/BookStackApp/BookStack/blob/development/dev/docs/logical-theme-system.md" target="_blank" rel="noopener noreferrer">Logical Theme System</a> -
  22         Methods to extend back-end functionality within BookStack.
  23     </li>
  24 </ul>
  25
  26 <hr>
  27
  28 <h5 id="authentication" class="text-mono mb-m">Authentication</h5>
  29 <p>
  30     To access the API a user has to have the <em>"Access System API"</em> permission enabled on one of their assigned roles.
  31     Permissions to content accessed via the API is limited by the roles & permissions assigned to the user that's used to access the API.
  32 </p>
  33 <p>Authentication to use the API is primarily done using API Tokens. Once the <em>"Access System API"</em> permission has been assigned to a user, a "API Tokens" section should be visible when editing their user profile. Choose "Create Token" and enter an appropriate name and expiry date, relevant for your API usage then press "Save". A "Token ID" and "Token Secret" will be immediately displayed. These values should be used as a header in API HTTP requests in the following format:</p>
  34 <pre><code class="language-css">Authorization: Token &lt;token_id&gt;:&lt;token_secret&gt;</code></pre>
  35 <p>Here's an example of an authorized cURL request to list books in the system:</p>
  36 <pre><code class="language-shell">curl --request GET \
  37   --url https://example.com/api/books \
  38   --header 'Authorization: Token C6mdvEQTGnebsmVn3sFNeeuelGEBjyQp:NOvD3VlzuSVuBPNaf1xWHmy7nIRlaj22'</code></pre>
  39 <p>If already logged into the system within the browser, via a user account with permission to access the API, the system will also accept an existing session meaning you can browse API endpoints directly in the browser or use the browser devtools to play with the API.</p>
  40
  41 <hr>
  42
  43 <h5 id="request-format" class="text-mono mb-m">Request Format</h5>
  44
  45 <p>
  46     For endpoints in this documentation that accept data a "Body Parameters" table will be available to show the parameters that are accepted in the request.
  47     Any rules for the values of such parameters, such as the data-type or if they're required, will be shown alongside the parameter name.
  48 </p>
  49
  50 <p>
  51     The API can accept request data in the following <code>Content-Type</code> formats:
  52 </p>
  53
  54 <ul>
  55     <li>application/json</li>
  56     <li>application/x-www-form-urlencoded*</li>
  57     <li>multipart/form-data*</li>
  58 </ul>
  59
  60 <p>
  61     <em>
  62         * Form requests currently only work for POST requests due to how PHP handles request data.
  63         If you need to use these formats for PUT or DELETE requests you can work around this limitation by
  64         using a POST request and providing a "_method" parameter with the value equal to
  65         <code>PUT</code> or <code>DELETE</code>.
  66     </em>
  67 </p>
  68
  69 <p>
  70     <em>
  71         * Form requests can accept boolean (<code>true</code>/<code>false</code>) values via a <code>1</code> or <code>0</code>.
  72     </em>
  73 </p>
  74
  75 <p>
  76     Regardless of format chosen, ensure you set a <code>Content-Type</code> header on requests so that the system can correctly parse your request data.
  77     The API is primarily designed to be interfaced using JSON, since responses are always in JSON format, hence examples in this documentation will be shown as JSON.
  78     Some endpoints, such as those that receive file data, may require the use of <code>multipart/form-data</code>. This will be mentioned within the description for such endpoints.
  79 </p>
  80
  81 <p>
  82     Some data may be expected in a more complex nested structure such as a nested object or array.
  83     These can be sent in non-JSON request formats using square brackets to denote index keys or property names.
  84     Below is an example of a JSON request body data and it's equivalent x-www-form-urlencoded representation.
  85 </p>
  86
  87 <p><strong>JSON</strong></p>
  88
  89 <pre><code class="language-json">{
  90   "name": "My new item",
  91   "locked": true,
  92   "books": [105, 263],
  93   "tags": [{"name": "Tag Name", "value": "Tag Value"}],
  94 }</code></pre>
  95
  96 <p><strong>x-www-form-urlencoded</strong></p>
  97
  98 <pre><code class="language-text">name=My%20new%20item&locked=1&books%5B0%5D=105&books%5B1%5D=263&tags%5B0%5D%5Bname%5D=Tag%20Name&tags%5B0%5D%5Bvalue%5D=Tag%20Value</code></pre>
  99
 100 <p><strong>x-www-form-urlencoded (Decoded for readability)</strong></p>
 101
 102 <pre><code class="language-text">name=My new item
 103 locked=1
 104 books[0]=105
 105 books[1]=263
 106 tags[0][name]=Tag Name
 107 tags[0][value]=Tag Value</code></pre>
 108
 109 <hr>
 110
 111 <h5 id="listing-endpoints" class="text-mono mb-m">Listing Endpoints</h5>
 112 <p>Some endpoints will return a list of data models. These endpoints will return an array of the model data under a <code>data</code> property along with a numeric <code>total</code> property to indicate the total number of records found for the query within the system. Here's an example of a listing response:</p>
 113 <pre><code class="language-json">{
 114   "data": [
 115     {
 116       "id": 1,
 117       "name": "BookStack User Guide",
 118       "slug": "bookstack-user-guide",
 119       "description": "This is a general guide on using BookStack on a day-to-day basis.",
 120       "created_at": "2019-05-05 21:48:46",
 121       "updated_at": "2019-12-11 20:57:31",
 122       "created_by": 1,
 123       "updated_by": 1,
 124       "image_id": 3
 125     }
 126   ],
 127   "total": 16
 128 }</code></pre>
 129 <p>
 130     There are a number of standard URL parameters that can be supplied to manipulate and page through the results returned from a listing endpoint:
 131 </p>
 132 <table class="table">
 133     <tr>
 134         <th width="110">Parameter</th>
 135         <th>Details</th>
 136         <th width="30%">Examples</th>
 137     </tr>
 138     <tr>
 139         <td>count</td>
 140         <td>
 141             Specify how many records will be returned in the response. <br>
 142             (Default: {{ config('api.default_item_count') }}, Max: {{ config('api.max_item_count') }})
 143         </td>
 144         <td>Limit the count to 50<br><code>?count=50</code></td>
 145     </tr>
 146     <tr>
 147         <td>offset</td>
 148         <td>
 149             Specify how many records to skip over in the response. <br>
 150             (Default: 0)
 151         </td>
 152         <td>Skip over the first 100 records<br><code>?offset=100</code></td>
 153     </tr>
 154     <tr>
 155         <td>sort</td>
 156         <td>
 157             Specify what field is used to sort the data and the direction of the sort (Ascending or Descending).<br>
 158             Value is the name of a field, A <code>+</code> or <code>-</code> prefix dictates ordering. <br>
 159             Direction defaults to ascending. <br>
 160             Can use most fields shown in the response.
 161         </td>
 162         <td>
 163             Sort by name ascending<br><code>?sort=+name</code> <br> <br>
 164             Sort by "Created At" date descending<br><code>?sort=-created_at</code>
 165         </td>
 166     </tr>
 167     <tr>
 168         <td>filter[&lt;field&gt;]</td>
 169         <td>
 170             Specify a filter to be applied to the query. Can use most fields shown in the response. <br>
 171             By default a filter will apply a "where equals" query but the below operations are available using the format filter[&lt;field&gt;:&lt;operation&gt;] <br>
 172             <table>
 173                 <tr>
 174                     <td>eq</td>
 175                     <td>Where <code>&lt;field&gt;</code> equals the filter value.</td>
 176                 </tr>
 177                 <tr>
 178                     <td>ne</td>
 179                     <td>Where <code>&lt;field&gt;</code> does not equal the filter value.</td>
 180                 </tr>
 181                 <tr>
 182                     <td>gt</td>
 183                     <td>Where <code>&lt;field&gt;</code> is greater than the filter value.</td>
 184                 </tr>
 185                 <tr>
 186                     <td>lt</td>
 187                     <td>Where <code>&lt;field&gt;</code> is less than the filter value.</td>
 188                 </tr>
 189                 <tr>
 190                     <td>gte</td>
 191                     <td>Where <code>&lt;field&gt;</code> is greater than or equal to the filter value.</td>
 192                 </tr>
 193                 <tr>
 194                     <td>lte</td>
 195                     <td>Where <code>&lt;field&gt;</code> is less than or equal to the filter value.</td>
 196                 </tr>
 197                 <tr>
 198                     <td>like</td>
 199                     <td>
 200                         Where <code>&lt;field&gt;</code> is "like" the filter value. <br>
 201                         <code>%</code> symbols can be used as wildcards.
 202                     </td>
 203                 </tr>
 204             </table>
 205         </td>
 206         <td>
 207             Filter where id is 5: <br><code>?filter[id]=5</code><br><br>
 208             Filter where id is not 5: <br><code>?filter[id:ne]=5</code><br><br>
 209             Filter where name contains "cat": <br><code>?filter[name:like]=%cat%</code><br><br>
 210             Filter where created after 2020-01-01: <br><code>?filter[created_at:gt]=2020-01-01</code>
 211         </td>
 212     </tr>
 213 </table>
 214
 215 <hr>
 216
 217 <h5 id="error-handling" class="text-mono mb-m">Error Handling</h5>
 218 <p>
 219     Successful responses will return a 200 or 204 HTTP response code. Errors will return a 4xx or a 5xx HTTP response code depending on the type of error. Errors follow a standard format as shown below. The message provided may be translated depending on the configured language of the system in addition to the API users' language preference. The code provided in the JSON response will match the HTTP response code.
 220 </p>
 221
 222 <pre><code class="language-json">{
 223         "error": {
 224                 "code": 401,
 225                 "message": "No authorization token found on the request"
 226         }
 227 }
 228 </code></pre>
 229
 230 <hr>
 231
 232 <h5 id="rate-limits" class="text-mono mb-m">Rate Limits</h5>
 233 <p>
 234     The API has built-in per-user rate-limiting to prevent potential abuse using the API.
 235     By default, this is set to 180 requests per minute but this can be changed by an administrator
 236     by setting an "API_REQUESTS_PER_MIN" .env option like so:
 237 </p>
 238
 239 <pre><code class="language-bash"># The number of API requests that can be made per minute by a single user.
 240 API_REQUESTS_PER_MIN=180</code></pre>
 241
 242 <p>
 243     When the limit is reached you will receive a 429 "Too Many Attempts." error response.
 244     It's generally good practice to limit requests made from your API client, where possible, to avoid
 245     affecting normal use of the system caused by over-consuming system resources.
 246     Keep in mind there may be other rate-limiting factors such as web-server & firewall controls.
 247 </p>
 248
 249 <hr>
 250
 251 <h5 id="content-security" class="text-mono mb-m">Content Security</h5>
 252 <p>
 253     Many of the available endpoints will return content that has been provided by user input.
 254     Some of this content may be provided in a certain data-format (Such as HTML or Markdown for page content).
 255     Such content is not guaranteed to be safe so keep security in mind when dealing with such user-input.
 256     In some cases, the system will apply some filtering to content in an attempt to prevent certain vulnerabilities, but
 257     this is not assured to be a bullet-proof defence.
 258 </p>
 259 <p>
 260     Within its own interfaces, unless disabled, the system makes use of Content Security Policy (CSP) rules to heavily negate
 261     cross-site scripting vulnerabilities from user content. If displaying user content externally, it's advised you
 262     also use defences such as CSP or the disabling of JavaScript completely.
 263 </p>