From c58caf35507737d2bcc6201097666861852299d6 Mon Sep 17 00:00:00 2001
From: Michael Friedrich <michael.friedrich@icinga.com>
Date: Thu, 12 Apr 2018 19:44:58 +0200
Subject: [PATCH] Add global API parameters to the docs; Add API
 troubleshooting section

---
 doc/12-icinga2-api.md     | 23 ++++++++++++++++++++++-
 doc/15-troubleshooting.md | 27 +++++++++++++++++++++++++++
 2 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/doc/12-icinga2-api.md b/doc/12-icinga2-api.md
index 48d96e699..c05522999 100644
--- a/doc/12-icinga2-api.md
+++ b/doc/12-icinga2-api.md
@@ -103,7 +103,7 @@ The output will be sent back as a JSON object:
 
 > **Tip**
 >
-> You can use the `pretty` parameter to beautify the JSON response with Icinga v2.9+.
+> You can use the [pretty](12-icinga2-api.md#icinga2-api-parameters-global) parameter to beautify the JSON response with Icinga v2.9+.
 
 You can also use [jq](https://stedolan.github.io/jq/) or `python -m json.tool`
 in combination with curl on the CLI.
@@ -272,6 +272,27 @@ Here are the exact same query parameters as a JSON object:
 The [match function](18-library-reference.md#global-functions-match) is available as global function
 in Icinga 2.
 
+### Global Parameters <a id="icinga2-api-parameters-global"></a>
+
+Name            | Description
+----------------|--------------------
+pretty          | Pretty-print the JSON response.
+verbose         | Add verbose debug information inside the `diagnostic_information` key into the response if available. This helps with troubleshooting failing requests.
+
+Example as URL parameter:
+
+```
+/v1/objects/hosts?pretty=1
+```
+
+Example as JSON object:
+
+```
+{ "pretty": true }
+```
+
+Both parameters have been added in Icinga 2 v2.9.
+
 ### Request Method Override <a id="icinga2-api-requests-method-override"></a>
 
 `GET` requests do not allow you to send a request body. In case you cannot pass everything as URL
diff --git a/doc/15-troubleshooting.md b/doc/15-troubleshooting.md
index c0fad94f6..8e1fc63ff 100644
--- a/doc/15-troubleshooting.md
+++ b/doc/15-troubleshooting.md
@@ -702,6 +702,33 @@ Look into the log and check whether the feature logs anything specific for this
 grep GraphiteWriter /var/log/icinga2/icinga2.log
 ```
 
+## REST API Troubleshooting <a id="troubleshooting-api"></a>
+
+In order to analyse errors on API requests, you can explicitly enable the [verbose parameter](12-icinga2-api.md#icinga2-api-parameters-global).
+
+```
+$ curl -k -s -u root:icinga -H 'Accept: application/json' -X DELETE 'https://localhost:5665/v1/objects/hosts/example-cmdb?pretty=1&verbose=1'
+{
+    "diagnostic_information": "Error: Object does not exist.\n\n ....",
+    "error": 404.0,
+    "status": "No objects found."
+}
+```
+
+## REST API Troubleshooting: No Objects Found <a id="troubleshooting-api-no-objects-found"></a>
+
+Please note that the `404` status with no objects being found can also originate
+from missing or too strict object permissions for the authenticated user.
+
+This is a security feature to disable object name guessing. If this would not be the
+case, restricted users would be able to get a list of names of your objects just by
+trying every character combination.
+
+In order to analyse and fix the problem, please check the following:
+
+- use an administrative account with full permissions to check whether the objects are actually there.
+- verify the permissions on the affected ApiUser object and fix them.
+
 
 ## Certificate Troubleshooting <a id="troubleshooting-certificate"></a>