<h1 class="list-heading text-capitals mb-l">Getting Started</h1>
+<p class="mb-none">
+ This documentation covers use of the REST API. <br>
+ 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>.
+
+ <br> <br>
+ Some alternative options for extension and customization can be found below:
+</p>
+
+<ul>
+ <li>
+ <a href="{{ url('/settings/webhooks') }}" target="_blank" rel="noopener noreferrer">Webhooks</a> -
+ HTTP POST calls upon events occurring in BookStack.
+ </li>
+ <li>
+ <a href="https://github.com/BookStackApp/BookStack/blob/development/dev/docs/visual-theme-system.md" target="_blank" rel="noopener noreferrer">Visual Theme System</a> -
+ Methods to override views, translations and icons within BookStack.
+ </li>
+ <li>
+ <a href="https://github.com/BookStackApp/BookStack/blob/development/dev/docs/logical-theme-system.md" target="_blank" rel="noopener noreferrer">Logical Theme System</a> -
+ Methods to extend back-end functionality within BookStack.
+ </li>
+</ul>
+
+<hr>
+
<h5 id="authentication" class="text-mono mb-m">Authentication</h5>
<p>
To access the API a user has to have the <em>"Access System API"</em> permission enabled on one of their assigned roles.
<hr>
<h5 id="request-format" class="text-mono mb-m">Request Format</h5>
-<p>The API is primarily design to be interfaced using JSON so the majority of API endpoints, that accept data, will read JSON request data although <code>application/x-www-form-urlencoded</code> request data is also accepted. Endpoints that receive file data will need data sent in a <code>multipart/form-data</code> format although this will be highlighted in the documentation for such endpoints.</p>
-<p>For endpoints in this documentation that accept data, a "Body Parameters" table will be available showing the parameters that will accepted in the request. 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.</p>
+
+<p>
+ 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.
+ 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.
+</p>
+
+<p>
+ The API can accept request data in the following <code>Content-Type</code> formats:
+</p>
+
+<ul>
+ <li>application/json</li>
+ <li>application/x-www-form-urlencoded*</li>
+ <li>multipart/form-data*</li>
+</ul>
+
+<p>
+ <em>
+ * Form requests currently only work for POST requests due to how PHP handles request data.
+ If you need to use these formats for PUT or DELETE requests you can work around this limitation by
+ using a POST request and providing a "_method" parameter with the value equal to
+ <code>PUT</code> or <code>DELETE</code>.
+ </em>
+</p>
+
+<p>
+ 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.
+ 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.
+ 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.
+</p>
+
+<p>
+ Some data may be expected in a more complex nested structure such as a nested object or array.
+ These can be sent in non-JSON request formats using square brackets to denote index keys or property names.
+ Below is an example of a JSON request body data and it's equivalent x-www-form-urlencoded representation.
+</p>
+
+<p><strong>JSON</strong></p>
+
+<pre><code class="language-json">{
+ "name": "My new item",
+ "books": [105, 263],
+ "tags": [{"name": "Tag Name", "value": "Tag Value"}],
+}</code></pre>
+
+<p><strong>x-www-form-urlencoded</strong></p>
+
+<pre><code class="language-text">name=My%20new%20item&books%5B0%5D=105&books%5B1%5D=263&tags%5B0%5D%5Bname%5D=Tag%20Name&tags%5B0%5D%5Bvalue%5D=Tag%20Value</code></pre>
+
+<p><strong>x-www-form-urlencoded (Decoded for readability)</strong></p>
+
+<pre><code class="language-text">name=My new item
+books[0]=105
+books[1]=263
+tags[0][name]=Tag Name
+tags[0][value]=Tag Value</code></pre>
<hr>
"message": "No authorization token found on the request"
}
}
-</code></pre>
\ No newline at end of file
+</code></pre>
+
+<hr>
+
+<h5 id="rate-limits" class="text-mono mb-m">Rate Limits</h5>
+<p>
+ The API has built-in per-user rate-limiting to prevent potential abuse using the API.
+ By default, this is set to 180 requests per minute but this can be changed by an administrator
+ by setting an "API_REQUESTS_PER_MIN" .env option like so:
+</p>
+
+<pre><code class="language-bash"># The number of API requests that can be made per minute by a single user.
+API_REQUESTS_PER_MIN=180</code></pre>
+
+<p>
+ When the limit is reached you will receive a 429 "Too Many Attempts." error response.
+ It's generally good practice to limit requests made from your API client, where possible, to avoid
+ affecting normal use of the system caused by over-consuming system resources.
+ Keep in mind there may be other rate-limiting factors such as web-server & firewall controls.
+</p>
+
+<hr>
+
+<h5 id="content-security" class="text-mono mb-m">Content Security</h5>
+<p>
+ Many of the available endpoints will return content that has been provided by user input.
+ Some of this content may be provided in a certain data-format (Such as HTML or Markdown for page content).
+ Such content is not guaranteed to be safe so keep security in mind when dealing with such user-input.
+ In some cases, the system will apply some filtering to content in an attempt to prevent certain vulnerabilities, but
+ this is not assured to be a bullet-proof defence.
+</p>
+<p>
+ Within its own interfaces, unless disabled, the system makes use of Content Security Policy (CSP) rules to heavily negate
+ cross-site scripting vulnerabilities from user content. If displaying user content externally, it's advised you
+ also use defences such as CSP or the disabling of JavaScript completely.
+</p>
\ No newline at end of file
projects / bookstack / blobdiff