From 9dd736d4eb053daea9285f82358247a79e36c39d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= <markus.makela@mariadb.com>
Date: Thu, 12 Nov 2020 16:34:09 +0200
Subject: [PATCH] MXS-3245: Document /v1/maxscale/ REST API responses

---
 Documentation/REST-API/Resources-MaxScale.md | 48 ++++++++++----------
 1 file changed, 24 insertions(+), 24 deletions(-)

diff --git a/Documentation/REST-API/Resources-MaxScale.md b/Documentation/REST-API/Resources-MaxScale.md
index 01c0337a7..c3a7bf4a3 100644
--- a/Documentation/REST-API/Resources-MaxScale.md
+++ b/Documentation/REST-API/Resources-MaxScale.md
@@ -25,7 +25,7 @@ file locations, configuration options and version information.
     },
     "data": {
         "attributes": {
-            "parameters": {
+            "parameters": { // Core MaxScale parameters
                 "libdir": "/usr/lib64/maxscale",
                 "datadir": "/var/lib/maxscale",
                 "process_datadir": "/var/lib/maxscale/data16218",
@@ -58,11 +58,11 @@ file locations, configuration options and version information.
                 "dump_last_statements": "never",
                 "load_persisted_configs": false
             },
-            "version": "2.3.6",
-            "commit": "47158faf12c156775c39388652a77f8a8c542d28",
-            "started_at": "Thu, 04 Apr 2019 21:04:06 GMT",
-            "activated_at": "Thu, 04 Apr 2019 21:04:06 GMT",
-            "uptime": 337
+            "version": "2.3.6", // The MaxScale version
+            "commit": "47158faf12c156775c39388652a77f8a8c542d28", // Commit that MaxScale was built from
+            "started_at": "Thu, 04 Apr 2019 21:04:06 GMT", // The time when MaxScale was started
+            "activated_at": "Thu, 04 Apr 2019 21:04:06 GMT", // The last time when the `passive` parameter was set to `false`
+            "uptime": 337 // How many seconds MaxScale has been running
         },
         "id": "maxscale",
         "type": "maxscale"
@@ -300,7 +300,7 @@ location where the log files are stored.
     },
     "data": {
         "attributes": {
-            "parameters": {
+            "parameters": { // Logging parameters
                 "highprecision": false,
                 "maxlog": true,
                 "syslog": true,
@@ -315,8 +315,8 @@ location where the log files are stored.
                 "log_debug": false,
                 "log_to_shm": false
             },
-            "log_file": "/home/markusjm/build/log/maxscale/maxscale.log",
-            "log_priorities": [
+            "log_file": "/home/markusjm/build/log/maxscale/maxscale.log", // The file MaxScale is logging into if `maxlog` is enabled
+            "log_priorities": [ // Active log priorities
                 "error",
                 "warning",
                 "notice",
@@ -410,22 +410,22 @@ valid loaded module.
             "description": "Firewall Filter",
             "api": "filter",
             "status": "GA",
-            "commands": [
+            "commands": [ // List of module commands
                 {
-                    "id": "rules/reload",
+                    "id": "rules/reload", // Name of the command
                     "type": "module_command",
                     "links": {
                         "self": "http://localhost:8989/v1/modules/dbfwfilter/rules/reload"
                     },
                     "attributes": {
-                        "method": "POST",
-                        "arg_min": 1,
-                        "arg_max": 2,
-                        "parameters": [
+                        "method": "POST", // Whether POST or GET should be used to call this command
+                        "arg_min": 1, // Minimum number of arguments
+                        "arg_max": 2, // Maximum number of arguments
+                        "parameters": [ // Parameter types for the command
                             {
-                                "description": "Filter to reload",
-                                "type": "FILTER",
-                                "required": true
+                                "description": "Filter to reload", // Parameter description
+                                "type": "FILTER", // Value type
+                                "required": true // Whether the parameter is required
                             },
                             {
                                 "description": "Path to rule file",
@@ -436,15 +436,15 @@ valid loaded module.
                     }
                 }
             ],
-            "parameters": [
+            "parameters": [ // Module parameters
                 {
-                    "name": "rules",
-                    "type": "path"
+                    "name": "rules", // Parameter name
+                    "type": "path" // Parameter type
                 },
                 {
                     "name": "log_match",
                     "type": "bool",
-                    "default_value": "false"
+                    "default_value": "false" // Default value of the parameter
                 },
                 {
                     "name": "log_no_match",
@@ -455,7 +455,7 @@ valid loaded module.
                     "name": "action",
                     "type": "enum",
                     "default_value": "block",
-                    "enum_values": [
+                    "enum_values": [ // Accepted enumeration values
                         "allow",
                         "block",
                         "ignore"
@@ -563,7 +563,7 @@ Command with output:
     "links": {
         "self": "http://localhost:8989/v1/maxscale/modules/dbfwfilter/rules/json"
     },
-    "meta": [
+    "meta": [ // Output of module command (module dependent)
         {
             "name": "test3",
             "type": "COLUMN",