From 760eff397f51e1bb616202dc6a8561ea52bac3a8 Mon Sep 17 00:00:00 2001 From: Dan Brown Date: Tue, 23 Aug 2022 17:05:42 +0100 Subject: [PATCH] Updated API docs with better request format explanation Explained the content-types accepted by BookStack. Made it clear that 'Content-Type' is expected on requests. Added example to shown how to achieve more complex formats using non-json requests. Also added link to api-scripts repo. Related to #3666 and #3652 --- .../api-docs/parts/getting-started.blade.php | 52 ++++++++++++++++++- 1 file changed, 50 insertions(+), 2 deletions(-) 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:

@@ -38,8 +41,53 @@
Request Format
-

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