From 45e1b74f369ccd49493fb830c78526dd8b2cb12e Mon Sep 17 00:00:00 2001
From: Ad Schellevis <ad@opnsense.org>
Date: Thu, 24 Nov 2022 18:57:04 +0100
Subject: [PATCH] Development Manual / API reference - Firewall and firewall
 plugin additions.

o point people seeking for an API to manage rules to the os-firewall plugin
o in the plugin, remove the quote about future plans as these might change and doesn't add much to the topic
o explain general plugin usage in case anyone missed that
o provide a general tip on how to debug issues with API's while explaining the scope of the work at hand.

closes https://github.com/opnsense/docs/pull/437
---
 source/development/api/core/firewall.rst.in   | 22 +++++++++++++++++++
 .../development/api/plugins/firewall.rst.in   | 16 +++++++++++---
 2 files changed, 35 insertions(+), 3 deletions(-)
 create mode 100644 source/development/api/core/firewall.rst.in

diff --git a/source/development/api/core/firewall.rst.in b/source/development/api/core/firewall.rst.in
new file mode 100644
index 00000000..012682a5
--- /dev/null
+++ b/source/development/api/core/firewall.rst.in
@@ -0,0 +1,22 @@
+.. _api_core_firewall:
+
+{{ title }}
+{{ title_underline }}
+{% for controller in controllers %}
+.. csv-table:: {{controller.type}} ({{controller.filename}})
+   :header: "Method", "Module", "Controller", "Command", "Parameters"
+   :widths: 4, 15, 15, 30, 40
+{%     for endpoint in controller.endpoints %}
+    "``{{endpoint.method}}``","{{endpoint.module}}","{{endpoint.controller}}","{{endpoint.command}}","{{endpoint.parameters}}"
+{%-    endfor %}
+{%-    if controller.uses %}
+{%         for use in controller.uses %}
+    "``<<uses>>``", "", "", "", "*{{use.type}}* `{{use.name}} <{{use.link}}>`__"
+{%-        endfor %}
+{%-    endif %}
+{% endfor %}
+
+.. Tip::
+
+    In order to inject rules using an API, you may take a look at the :ref:`Firewall Plugin API <api_plugins_firewall>`,
+    currently the core system does not support rule modifications via the api for this topic.
diff --git a/source/development/api/plugins/firewall.rst.in b/source/development/api/plugins/firewall.rst.in
index aef94a7d..a5cb111e 100644
--- a/source/development/api/plugins/firewall.rst.in
+++ b/source/development/api/plugins/firewall.rst.in
@@ -1,9 +1,19 @@
+.. _api_plugins_firewall:
+
 {{ title }}
 {{ title_underline }}
 
-The firewall API plugin is a first step into migrating the legacy firewall components from OPNsense, although it does contain
-a user interface, it's main focus is only to provide machine to machine interaction between custom applications and OPNsense
-for selected features.
+The firewall API plugin (**os-firewall**) offers a way for machine to machine interaction between custom applications and OPNsense, it can
+easily be installed like any other plugin via :menuselection:`System --> Firmware --> Plugins`.
+
+Although the plugin does contains a basic user interface (in :menuselection:`Firewall --> Automation`), it's mirely intended
+as a reference and testbed. There's no relation to any of the rules being managed via the core system.
+
+.. Tip::
+
+    Use your browsers "inspect" feature to compare requests easily, the user interface in terms of communication is exactly the same
+    as offered by the API . Rules not visible in the web interface will not be returned by the API either.
+
 
 {% for controller in controllers %}
 .. csv-table:: {{controller.type}} ({{controller.filename}}) {% if not controller.is_abstract %} -- extends : {{controller.base_class}} {% endif %}