Add GET /config/_topics which will be helpful when automatically generating a Pi-hole settings page

Signed-off-by: DL6ER <dl6er@dl6er.de>

src/api/api.c

@@ -66,6 +66,7 @@ static struct {
 	{ "/api/stats/database/upstreams",          "",                           api_stats_database_upstreams,          { false, 0             }, true,  HTTP_GET },
 	{ "/api/version",                           "",                           api_version,                           { false, 0             }, true,  HTTP_GET },
 	{ "/api/auth",                              "",                           api_auth,                              { false, 0             }, false, HTTP_GET | HTTP_POST | HTTP_DELETE },
+	{ "/api/config/_topics",                    "",                           api_config_topics,                     { false, 0             }, true,  HTTP_GET },
 	{ "/api/config",                            "",                           api_config,                            { false, 0             }, true,  HTTP_GET | HTTP_PUT },
 	{ "/api/config",                            "/{element}",                 api_config,                            { false, 0             }, true,  HTTP_GET | HTTP_PUT },
 	{ "/api/config",                            "/{element}/{value}",         api_config,                            { false, 0             }, true,  HTTP_DELETE | HTTP_PATCH },

src/api/api.h

@@ -51,7 +51,10 @@ int api_ftl_dbinfo(struct ftl_conn *api);
 int api_ftl_sysinfo(struct ftl_conn *api);
 int get_ftl_obj(struct ftl_conn *api, cJSON *ftl, const bool is_locked);
 int get_system_obj(struct ftl_conn *api, cJSON *system);
+
+// Config methods
 int api_config(struct ftl_conn *api);
+int api_config_topics(struct ftl_conn *api);
 
 // Log methods
 int api_logs(struct ftl_conn *api);

src/api/config.c

@@ -25,6 +25,22 @@
 // shm_lock()
 #include "shmem.h"
 
+static struct {
+	const char *name;
+	const char *description;
+} config_topics[] =
+{
+	{ "dns", "DNS server settings" },
+	{ "dnsmasq", "dnsmasq settings" },
+	{ "resolver", "Resolver settings" },
+	{ "database", "Database settings" },
+	{ "api", "API settings" },
+	{ "http", "HTTP settings" },
+	{ "files", "File locations" },
+	{ "misc", "Miscellaneous settings" },
+	{ "debug", "Debug settings" }
+};
+
 // The following functions are used to create the JSON output
 // of the /api/config endpoint.
 
@@ -755,3 +771,20 @@ int api_config(struct ftl_conn *api)
 
 	return 0;
 }
+
+int api_config_topics(struct ftl_conn *api)
+{
+	cJSON *topics = JSON_NEW_ARRAY();
+	for(unsigned int i = 0; i < sizeof(config_topics)/sizeof(*config_topics); i++)
+	{
+		cJSON *topic = JSON_NEW_OBJECT();
+		JSON_REF_STR_IN_OBJECT(topic, "name", config_topics[i].name);
+		JSON_REF_STR_IN_OBJECT(topic, "description", config_topics[i].description);
+		JSON_ADD_ITEM_TO_ARRAY(topics, topic);
+	}
+
+	// Build and return JSON response
+	cJSON *json = JSON_NEW_OBJECT();
+	JSON_ADD_ITEM_TO_OBJECT(json, "topics", topics);
+	JSON_SEND_OBJECT(json);
+}

src/api/docs/content/specs/config.yaml

@@ -145,6 +145,30 @@ components:
               application/json:
                 schema:
                   $ref: 'common.yaml#/components/errors/unauthorized'
+    topics:
+      get:
+        summary: Get configuration topics
+        tags:
+          - "Pi-hole Configuration"
+        operationId: "get_config_topics"
+        description: |
+          This API hook returns categories that may be used to group configuration options.
+        responses:
+          '200':
+            description: OK
+            content:
+              application/json:
+                schema:
+                  $ref: 'config.yaml#/components/schemas/topics'
+                examples:
+                  topics:
+                    $ref: 'config.yaml#/components/examples/topics'
+          '401':
+            description: Unauthorized
+            content:
+              application/json:
+                schema:
+                  $ref: 'common.yaml#/components/errors/unauthorized'
   schemas:
     config:
       type: object
@@ -465,6 +489,21 @@ components:
                   type: boolean
                 reserved:
                   type: boolean
+    topics:
+      type: object
+      properties:
+        topics:
+          type: array
+          items:
+            type: object
+            properties:
+              name:
+                type: string
+                description: The name of the topic
+              description:
+                type: string
+                description: A human-readable description of the topic
+
   examples:
     config:
       summary: The entire configuration
@@ -629,6 +668,28 @@ components:
               mozillaCanary: true
           misc:
             nice: -10
+    topics:
+      summary: All topics
+      value:
+        topics:
+          - name: DNS
+            description: DNS settings
+          - name: dnsmasq
+            description: dnsmasq settings
+          - name: Resolver
+            description: Resolver settings
+          - name: Database
+            description: Database settings
+          - name: API
+            description: API settings
+          - name: HTTP
+            description: HTTP settings
+          - name: Files
+            description: File locations
+          - name: Miscellaneous
+            description: Miscellaneous settings
+          - name: Debug
+            description: Debug settings
     errors:
       bad_request:
         invalid_path_depth:

src/api/docs/content/specs/main.yaml

@@ -161,6 +161,9 @@ paths:
   /config:
     $ref: 'config.yaml#/components/paths/config'
 
+  /config/_topics:
+    $ref: 'config.yaml#/components/paths/topics'
+
   /config/{element}:
     $ref: 'config.yaml#/components/paths/config_elem'