doveadm: Improve HTTP API documentation

Author: slusarz

docs/core/admin/doveadm.md

@@ -101,27 +101,54 @@ service doveadm {
 Connecting to the endpoint can be done by using standard HTTP protocol and
 authentication headers.
 
-To get list the commands supported by the endpoint, the following example
-commands can be used:
+::: info
+There is also https://github.com/dovecot/doveadm-http-cli that can be
+used for accessing the API.
+:::
+
+All doveadm commands are accessed under the `/doveadm/v1` path.
+
+#### Command List
 
-#### `X-Dovecot-API` Auth
+To get the list of commands supported by the endpoint, send an authenticated
+GET request to the root of the endpoint (for all endpoint commands), or to
+`/doveadm/v1` path (for doveadm API commands).
+
+For example, using [[setting,doveadm_password]] authentication:
 
 ```console
-$ curl -H "Authorization: X-Dovecot-API <base64 dovecot_api_key>" \
-      http://host:port/doveadm/v1
+curl -X GET –u doveadm:password http://host:port/
 ```
 
-#### Basic Auth
+#### Authentication
+
+##### Basic Auth
+
+Use password as configured in [[setting,doveadm_password]]. User name is
+`doveadm`.
 
 ```
 curl -H "Authorization: Basic <base64 doveadm:doveadm_password>" http://host:port/doveadm/v1
+```
+
+or
+
+```console
 curl –u doveadm:password http://host:port/doveadm/v1
 ```
 
-There is also https://github.com/dovecot/doveadm-http-cli that can be
-used for accessing the API.
+##### `X-Dovecot-API` Auth
+
+Use API Key as configured in [[setting,doveadm_api_key]].
 
-### API overview
+```console
+$ curl -H "Authorization: X-Dovecot-API <base64 dovecot_api_key>" \
+      http://host:port/doveadm/v1
+```
+
+### API Overview
+
+#### Request
 
 All commands sent to the API needs to be posted in json format using
 `Content-Type: application/json` in headers for the request type and the
@@ -176,30 +203,28 @@ Also it is not guaranteed that the commands will be processed in order.
 All commands are case sensitive.
 :::
 
-### Example Session
-
-Reload Dovecot configuration:
+#### Response
 
-```json
-[
-    [
-        "reload",
-        {},
-        "tag1"
-    ]
-]
-```
+Requests that fail *before* the doveadm command is run returns 400/500
+HTTP response codes:
 
-Then we execute it with curl:
+| Code | Reason |
+| ---- | ------ |
+| 400 | Invalid request. Response body contains error message in text/plain. |
+| 401 | Unauthorized (missing authentication). |
+| 403 | Forbidden (authentication failed). |
+| 404 | Unknown doveadm command. |
+| 500 | Internal server error (see Dovecot logs for more information). |
 
-```console
-$ curl -v -u doveadm:secretpassword -X POST http://localhost:8080/doveadm/v1 \
-      -H "Content-Type: application/json" -d '[["reload",{},"tag1"]]'
-```
+Otherwise, the response will be a 200 code, Content-Type `application/json`,
+and the body will be a JSON object.
 
-This is equivalent to the command [[doveadm,reload]].
+##### Success
 
-Successful Response:
+::: info Note
+All data returned in the JSON object will be strings (e.g., counting fields
+will be strings, not numbers/integers).
+:::
 
 ```json
 [
@@ -211,7 +236,10 @@ Successful Response:
 ]
 ```
 
-Failure Response:
+##### Failure
+
+`exitCode` are the [[link,doveadm_error_codes]].
+
 ```json
 [
     [
@@ -225,6 +253,29 @@ Failure Response:
 ]
 ```
 
+### Example Session
+
+Reload Dovecot configuration:
+
+```json
+[
+    [
+        "reload",
+        {},
+        "tag1"
+    ]
+]
+```
+
+Then we execute it with curl:
+
+```console
+$ curl -v -u doveadm:secretpassword -X POST http://localhost:8080/doveadm/v1 \
+      -H "Content-Type: application/json" -d '[["reload",{},"tag1"]]'
+```
+
+This is equivalent to the command [[doveadm,reload]].
+
 ## Mailbox Commands
 
 These commands should be run on one of the Dovecot proxies. The proxy is then