This documentation covers use of the REST API.
+ Examples of API usage, in a variety of programming languages, can be found in the BookStack api-scripts repo on GitHub.
+
+
Some alternative options for extension and customization can be found below:
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 application/x-www-form-urlencoded request data is also accepted. Endpoints that receive file data will need data sent in a multipart/form-data format although this will be highlighted in the documentation for such endpoints.
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.
+ ++ 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. +
+ +
+ The API can accept request data in the following Content-Type formats:
+
+
+ * 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
+ PUT or DELETE.
+
+
+
+ * Form requests can accept boolean (true/false) values via a 1 or 0.
+
+
+ Regardless of format chosen, ensure you set a Content-Type 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 multipart/form-data. This will be mentioned within the description for such endpoints.
+
+ 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. +
+ +JSON
+ +{
+ "name": "My new item",
+ "locked": true,
+ "books": [105, 263],
+ "tags": [{"name": "Tag Name", "value": "Tag Value"}],
+}x-www-form-urlencoded
+ +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%20Valuex-www-form-urlencoded (Decoded for readability)
+ +name=My new item
+locked=1
+books[0]=105
+books[1]=263
+tags[0][name]=Tag Name
+tags[0][value]=Tag Value+ 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. +
++ 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.
\ No newline at end of file