diff --git a/resources/views/api-docs/parts/getting-started.blade.php b/resources/views/api-docs/parts/getting-started.blade.php index 0d271ec5d..76da73e45 100644 --- a/resources/views/api-docs/parts/getting-started.blade.php +++ b/resources/views/api-docs/parts/getting-started.blade.php @@ -2,6 +2,9 @@
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:
+
+ 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",
+ "books": [105, 263],
+ "tags": [{"name": "Tag Name", "value": "Tag Value"}],
+}
+
+x-www-form-urlencoded
+ +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
+
+x-www-form-urlencoded (Decoded for readability)
+ +name=My new item
+books[0]=105
+books[1]=263
+tags[0][name]=Tag Name
+tags[0][value]=Tag Value