<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>
HTTP POST calls upon events occurring in BookStack.
</li>
<li>
- <a href="https://github.com/BookStackApp/BookStack/blob/master/dev/docs/visual-theme-system.md" target="_blank" rel="noopener noreferrer">Visual Theme System</a> -
+ <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/master/dev/docs/logical-theme-system.md" target="_blank" rel="noopener noreferrer">Logical Theme System</a> -
+ <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="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>
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